blog.uncommons.org — Code-commenting is so basic and so universal that every programmer, regardless of the language that they practise, thinks that they know all there is to know.I don?t believe that I?ve read a piece of code and thought ?wow, this has far too many comments?. Unfortunately, I?ve had the opposite reaction all too often.
Jul 27, 2008 View in Crawl 4
krinthekuzJul 28, 2008
i definitely agree that one can have too many comments. in fact, most people who write comments "because the specs say to write comments" write really crappy comments like:i++; //iterate countercomments are for headings of sections, hacks/workarounds, sections of code where there are more than 2 operations in 1 line, or anything that you thought was novel when you originally wrote it. also, STOP USING 1 CHAR VARIABLES. i, j, and k are iterators. a, b, c, n, x, y, and z are numerical analysis operands that have a historical significance. if you're not using one of those letters for those reasons, you must use a full word.as for the example in the article, sqrtNewtonRaphson(double n, double tolerance)as a function name is good enough to explain those 4 lines of code without a comment (sqrt is square root is virtually every high level API; not following API conventions is a n00b mistake). combine that with the !1char rule and there's nothing in the function that is not immediately apparent from the name, and no comment is needed. if you cannot connect what those 5 lines mean without a comment that says "returns the square root of a number to a tolerance using the newton raphson method", then maybe you should look into doing web design.as others have pointed out, learn regex. if you don't know regex, you have no right to bitch when someone uses it and doesn't make a comment for it.
brendon2020Jul 28, 2008
i've got it, secret repo with commented code.
boruarJul 31, 2008
That's true that the comment are very import and for more clearly that you write the code always a comment can be more explained. But not for this reason if you use the comments you can forget do a clear code. I think that if your code is not understandable if because your code is written in a wrong way, and the first step is change it and at the end if you need some small clarification put a comment (like you are using the Newton-Raphson method) but not use a lot of comments as a rule
guvanteAug 4, 2008
The underlying problem in any discussion about comments is the inherent ambiguity.There are many forms of comments:JavaDoc comments: Always a good idea, gives your IDE the chance to give you hints as to the purpose of functions, as well as being easily convertible to API documentation if needed at a later date.How comments: Always a bad idea unless it could be catagorized elsewhere, these are the "Increment i" style of comments, and are never helpful, since they are simply you adding more characters without adding more informationWhy not *blank* comments: Always a good idea, gives the reason why you did not take the obvious solution, note that some of these could be categorized as "How" comments, since they may involve bugs in a compiler or other comments, or corner cases that need to be handled, but they help to explain your purpose and avoid someone else blindly changing to the "correct" solutionWhy comments: These are what Jeff was talking about, and they are definitely a odd child. For one, they help explain what the overall goal of your code is, which isn't always obvious given merely the code, but on the other hand, shouldn't the code be obvious in and of itself? If you have a case of Why not *blank* then it is understandable, or if the algorithm is extremely complex and tricky. But if the algorithm is extremely complex and tricky, shouldn't you verify that it needs to be like that? If possible it would be better to refactor your code to be less tricky, or more descriptive, and this was the point that Jeff was making, not that comments are evil, but that they are like a spice, in proper dosages they turn a great meal into perfection, but if used to cover up a lousy meal, they will at best make something barely palatable, or at worst make something that is inedible and not even as good as before the spices were added.So to summarize what my feelings And I believe Jeff's feelings):Comments are not a cure-all, good code often does not need to be commented, and good comments are often masking bad code. (Specifically in regards to Why code)
tflowholdingsAug 5, 2008
On one hand, we have people who don't code by the rules at all. On the other, we have people who follow them too closely or take them too seriously. One thing they never really taught us in college was a good way to comment code. Everyone thinks comments are not as important as the code they describe. This is true for a computer, but to a human developer, comments sway our minds more than the code itself. One thing that needs to be taught in school is how to properly write and *MAINTAIN* code comments. Here's a related digg:<a class="user" href="http://digg.com/programming/The_Dark_Side_of_Code_Commenting">http://digg.com/programming/The_Dark_Side_of_Code_ ...</a>
hgtechsolutionsAug 11, 2008
I too had noticed programmers not using comments with their code and later getting confused by not able to figure out what code is for what. Commenting not only helps you, but it also helps the other fellow programmers trying to understand your code at a later stage. Programmers should make it a habit to use comments.