There are at least two points of view, lets call them (a) and (b).
(A) A program should always contain elaborate comments to make it readable and maintainable.
(B) A program should be as much as possible self-documenting, with comments added sparingly only where the code itself is unclear.
Well, of course I'm for point (B)! What programmer doesn't want self-documenting code? Writing comments is probably more challenging then writing the actual code. Unfortunately life isn't so easy, and the code we write isn't always so clear or the language we use is just too ambiguous.
Comments might be a good idea, and essential in certain situations, but they can also be misused and overdone. I have seen many functions that had more than a paragraph of comments for one no more then two lines of code in a function. The function was very understandable and it's context wasn't a mystery either. But sometimes comments are just absent, like in this code sample (github/linux-2.6), which you can see that the first 2/3 of the file is lacking comments. Sure the code is readable and styled very well, but what about context?
In the case of programming language extensibility, where the programmer can add custom functionality, comments are an essential aspect of the code. This is even more true if the code is for a project with many programmers or for future maintenance purposes.
Although, point (A) does apply to certain languages like Scheme, or M, where the code is different and not as clear the the average reader. The code isn't self-explanatory. One of the greatest examples where this is true, is Assembly, or the Edsac. In the grander scheme of things, languages that lack uniformity, generality, or orthogonality are those that benefit from point (A).
Point (B) is a great ideal situation, but it sure is a dream. But lets not forget that the minimum amount of comments should be enough to at least generate documentation from the code.
What do you think?
No comments:
Post a Comment