Published: Jul 12 2013 / 15:42
#5 "Some comment styles can fill a lot of screen space." You can't be serious!
I agree, that's not really a valid concern as to comment or not (at least in general terms). What I found most striking is that the example code presented next to #5 completely contradicts his point. Descriptions of code blocks using a documentation-generating format is an example of some of the most useful kinds of comments. It seldom hurts to spare some screen space for the like.
... is an example of some of the most useful kinds of comments... For me, it's one of the worst comments, I don't need a comment if my code is already giving this info.
I think it really depends and maybe people should apply some judgment. I take your point that some blocks don't really need commentary, but I think those cases are the exceptions. I think it's usually worth a few lines for the author to give a high level description of his own thought patterns regarding problems and solutions because the semantics provided in programming languages are never sufficient to encompass the full range of human thought. Even spoken languages *very* often suffer from semantic ambiguity. Also, I consider commentary at the beginning of a code block to be better than commentary that is woven into the lines of the body itself because the physical layout of the code helps me to internalize the meaning. When commentary interrupts that flow, it also interrupts my process of assimilating the code.
If you maintain, modify or debug a non-trivial program, say more than 1K LOC, you need comments, lots of. Since programmers don't test their programs, we have to spend 85% reading programs and 15% coding. So I became documentation and comments enthusiast: we should have comments, diagrams, structure layouts, sql schemas, drawings embedded in the source code to help. It's a question of productivity. NOTE: a good source editor should have the function "Hide comments" just as some editors have "Collapse loop".
So we should blame programmers that don't test their code, not to use comments to hide it.
This is a good point. In many cases, writing good unit tests is the optimal way to "document" your code - i.e. "these are my assumptions", "this is what I've tested" is the best way to clue other people into what your code is meant to do.
I've usually found reading other's comments useless. Well written code has been more valuable to me.
Ah the irony.. hardly anyone comments on DZone.. but a post about code comments garners response. :) There is some point in making code so easily readable that comments aren't needed. That should be the goal. But where they are needed then do it to be kind to your fellow coders (or your future self). I think common sense over dogma wins every day. There've been times when I've come across beautifully written comments in applications. Often the code has reflected that same value - as if the author cared to communicate. Matt Sears Taco gem (https://github.com/mattsears/taco) is an example in the small. Clarity should be the goal, not just making the code work.
Perfect! Comments should be used in rare cases. The common sense should be write good code.
This whole article should be qualified--if your language of choice is sufficiently expressive to effectively convey the author's intent to humans without the reality of the underlying machine getting in the way, THEN it's best to have code that seldom needs non-code commentary. For example, the C language more closely models the mechanisms of a computer than the way people think about problems and their solutions. Naturally, it may be harder to achieve the desired quality of author-to-reader expression without comments for code in C.
Html tags not supported. Reply is editable for 5 minutes. Use [code lang="java|ruby|sql|css|xml"][/code] to post code snippets.