6 ms·
Coding Without Comments
- halo 18y agoIt wasn't the point of the article I now feel smug about being able to identify that Newton-Raphson implementation before reading the line below.
- greyman 18y agoWhile it is true that when some idea can be expressed by descriptive variable or function name, comment is not necessary. But there are many places in the code, where it is highly desirable to explain by plain words, why certain solution was adopted, that certain part is a bug fix, or why some part of the code is counter-intuitive. I for one am much more happier when my colleagues comment their code extensively. To look at it from the opposite side: Is there any inherent problem with having too much comments? (provided they are correct).
- stcredzero 18y agoIf you can't write intention revealing code, this often is a symptom! Most often this means that there are implicit rules written into your code base. 90% of the time or more these should be factored out! Also, another problem with too many comments: this is more stuff to maintain. Chances are, the programmer already has enough to do!
- newt0311 18y agoI disagree. Code without comments will never be as understandable as code with comments. This is true because code is designed partly for computers while comments can be written entirely for humans. This is important because comments only have to be written once and maintained occasionally while code without comments has to be reinterpreted every time it is read.
- procyon 18y agoNot quite! I think code can be written to make it self explanatory. With appropriate variable, function names along with proper abstraction and refactoring code can be read almost like a prose which eliminates need for comments. At times comments are too annoying because they state the obvious or they are not updated along with the code. eg: code like this in ruby can explain itself very well! display_error if not valid_input Now I do understand that comments cannot be replaced entirely and sometimes it is necessary to add notes to understand the code thus I prefer using comments sparingly and avoid long headers on top of each file. Those headers with author name, dates and other information is unnecessary if right tools are used to maintain your project.
- bkudria 18y agoYou mean: display_error unless valid_input right?
- comatose_kid 18y agoCode without comments is better than code with outdated comments - this happens quite frequently.
- ajross 18y agoAmen. Comments lie. This happens all the time. Programmers who try to maintain code by reference to the comments will get it wrong. You have to debug the code. Comments, at most, should be a guide to what happens where.
- axod 18y agoIt depends on how well you write your code. Also I think in general hackers should learn to read code. To reverse engineer. To understand what is going on without comments. Then when you do have some comments, it's a bonus (Or just even more confusing and contradictory).
- rw 18y agoYou can write a provable theorem as a stream of symbols from mathematical logic, instead of prose. But, do you really want to read the result? Code can be made clearer through abstraction, certainly, but comments are a domain specific language for helping humans understand computer programs.
- stcredzero 18y ago"This is true because code is designed partly for computers while comments can be written entirely for humans." There are differing degrees to which this is true. Different languages had different design motivations. Smalltalk was specifically designed to be readable by humans. By grade school aged humans, actually! In the Smalltalk community, most regard comments as a "Code Smell."
- noonespecial 18y agoThose comments he doesn't like are often required by coding practices in a team setting. Rightly so as there are often people of many different skill levels working on the same code.
- mynameishere 18y agoMy impression...as you become more experienced, your comments will tend more towards confession and pleas for forgiveness... //XXX I don't know why this works ... //XXX Worst kludge of my life ... //FIXME this whole pile of crap needs re-written
- spydez 18y agoMy favorite comment that I've personally written: // Here there be magic. See datasheet for details; they explain it // almost as well as I just did. (followed by ~10 lines of math chock full of magic numbers.)
- jgrahamc 18y agoI maintained a piece of 250,000 line C code that had one comment in it (apart from copyright notices): /* bad code */ To this day I do not know if this was a comment on the quality of the code that came after it, or if the developer was reprimanding the code.
- gruseom 18y agoComments like this seem cowardly to me. If you can do better, then do. If you can't, write the best code you can and be enough of a man or woman to commit what you did and not clutter it up with excuses.
- cconstantine 18y agoIn a perfect world those kinds of comments would never be written. Unfortunately there are times when there simply isn't time to do it the Right Way (tm). In those times when you have to do it the Fast and Ugly (tm) way, it's nice to make a comment that you really don't like the code. It adds some humor, and lets the maintainer know that there is no emotional attachment to that section of code.
- gruseom 18y agothere simply isn't time to do it the Right Way Of course, this is the first thing that everybody says. And since everybody says it, everybody thinks it must be true. But my experience has been that if you really want to do good work, it turns out not to be true (say) 80% of the time. So the next time you find yourself making a mess because you believe you "have to", you could try stopping and questioning that assumption. You might surprise yourself. How do you think I learned this? Certainly not by following what the majority of programmers believe. Edit: Rather than using phrases like "the Right Way", I'd suggest toning things down and looking for a way. There are many ways. If you get in the habit of thinking there's only one, and it's capitalized and trademarked, the bar seems a lot higher than it really is.
- culley 18y agoNot sure about you, but I learned to code by writing psuedo code. I routinely start with comments that psuedo code my idea and then add the sections of the code. If I can't remember how everything is supposed to work while I'm writing it, what hope does the intern 2 years from now have in adding a new feature?
- procyon 18y agoif a code is changed comments need to change too! Too many times I have seen out dated comments adding confusion to the code. If my code requires great deal of explanation, I go back to my drawing board and redesign the logic.
- dangoldin 18y agoVery applicable point. I keep on noticing this happen and I would prefer no comments to outdated comments.
- jacobbijani 18y agoYeah, sometimes if I'm doing a complex logic block I will just put the conditionals in and fill them in with a short description of what will be there. Generally, since I've already written them I just leave the comments in after I fill the real code in. I've noticed that my Javascript is usually very readable and doesn't require commenting for the most part. I think using MooTools has a lot to do with it, those libraries all encourage good naming practices.
- hs 18y agoas time goes, you need less comments
- dous 18y agoas time goes, people tend to write less comments
- hs 18y agoMost of the time I deleted my own comments after things become more obvious - I hate 'moving parts' in my code The trick is to highlight comments with bright & contrast fg/bg color combo that hurts your eyes (it also serves to say 'hi i'm comment, i'm important, but delete me when u understand me')
- nradov 18y agoHe missed the distinction between in-line comments and API comments. Pretty much all skilled developers would agree that in-line comments should be minimized, and used only when necessary to explain the reasoning behind a particular design, or to clarify a complex section that can't be refactored. But for API functions which you intend other developers to use as black boxes, you need to provide extensive comments clearly explaining the purpose, inputs, outputs, error conditions, and maybe even some sample code.
- ajross 18y agoThat's documentation, not comments. Nothing hurts code readability more than huge chunks of markup (markup!) getting in the way of the code you need to read to maintain. Javadocxygenwhatever generates pretty web pages, but leads to write-only source files.
- nradov 18y agoI appreciate the readability problem, but what would you propose as an alternative? In my experience, combining the code and documentation in a single file makes it much more likely that developers actually will update the documentation. Besides, any decent editor will hide the documentation if you don't want to see it.
- ajross 18y agoHow about abstraction? Draw a clean line between the API you're trying to document and the code that implements it, and make sure that comments for either don't cross-pollute. This is a good idea anyway. I can't tell you how many automatically generated documentation trees I've seen that are utterly worthless. Documentation of public interfaces gets mixed in with usage notes on internal structures, and you don't know what you're supposed to use.
- silentbicycle 18y agoThe worst comments are the ones that say, "this is awful, will fix later". I try to datestamp my comments, but I've seen some of the above with dates three years old. Why?
- gruseom 18y agoI already commented on this so I guess it must be a bit of a hobbyhorse, but I think I can answer your question. The comment really has nothing to do with coming back and fixing it later. It has to do with alleviating a feeling of guilt (or is that shame) about shoddy work. So the comment has served its purpose and that is why it is there. Once you make a point of never doing this, the psychological pressure has to find another outlet, such as just fixing the code in the first place.
- maxwell 18y agoTo some extent it depends on your language. jQuery seems about right for that kind of JavaScript. http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.js http://ajax.googleapis.com/ajax/libs/jquery/1.2.6/jquery.js
- boucher 18y agoActually, that seems like comment overkill to me. Almost every line has a comment.
- deleted 18y ago[deleted]
- hernan7 18y agoIf you document you need to keep the comments in sync with the code. If you write self-documenting code, you need to keep the function names in sync with the code. You just can't win...
- silentbicycle 18y agoWhat about assertions? They work well as comments, but they're actually tested, and you know immediately if they go out of date. You can decide one way or the other whether to compile them as no-ops in releases, but it seems like a big improvement either way.