What's wrong with comments that explain complex code?
after writing a complex piece of code written in a partly human-readable programming language, why not add a descriptive and concise comment explaining the operation of the code in friendly and understandable English? ...What's wrong with explaining complicated code with a comment?
-
Is the approach of avoiding commenting code to make people actually read the code and understand what is going on make sense in a medium-sized coding environment (one that can be reasonably read in whole by every person working on it within a month or two), or is it a recipe for a long-term disaster? What are the advantages and disadvantages of the approach?
At a first glance, above questions look quite similar to me. First looks like asking something like "what's wrong with following <particular approach>
", while second asks "is it okay to abstain of following <particular approach>
".
But both questions are somewhat broad and verbose and I am not fully certain that I figured the similarity correctly. Would appreciate an explanation if I miss some substantial difference between these questions.