Link Details

Link 996503 thumbnail
User 1159603 avatar

By pauloortins
via pauloortins.com
Published: Jul 12 2013 / 15:42

Comments

Add your comment
User 368023 avatar

yakkoh replied ago:

1 votes Vote down Vote up Reply

#5 "Some comment styles can fill a lot of screen space." You can't be serious!

User 218789 avatar

eelmore replied ago:

1 votes Vote down Vote up Reply

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.

User 1159603 avatar

pauloortins replied ago:

0 votes Vote down Vote up Reply

... 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.

User 218789 avatar

eelmore replied ago:

1 votes Vote down Vote up Reply

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.

User 1159603 avatar

pauloortins replied ago:

0 votes Vote down Vote up Reply

why ?

User 368023 avatar

yakkoh replied ago:

1 votes Vote down Vote up Reply

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".

User 1159603 avatar

pauloortins replied ago:

0 votes Vote down Vote up Reply

So we should blame programmers that don't test their code, not to use comments to hide it.

User 330966 avatar

ferrisoxide replied ago:

0 votes Vote down Vote up Reply

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.

User 730405 avatar

mrtwilson replied ago:

0 votes Vote down Vote up Reply

I've usually found reading other's comments useless. Well written code has been more valuable to me.

User 330966 avatar

ferrisoxide replied ago:

0 votes Vote down Vote up Reply

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.

User 1159603 avatar

pauloortins replied ago:

0 votes Vote down Vote up Reply

Perfect! Comments should be used in rare cases. The common sense should be write good code.

User 218789 avatar

eelmore replied ago:

1 votes Vote down Vote up Reply

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.

Add your comment


Html tags not supported. Reply is editable for 5 minutes. Use [code lang="java|ruby|sql|css|xml"][/code] to post code snippets.

Voters For This Link (10)



Voters Against This Link (4)



Java Performance Optimization
Written by: Pierre-Hugues Charbonneau
Featured Refcardz: Top Refcardz:
  1. Design Patterns
  2. OO JS
  3. Cont. Delivery
  4. Java EE7
  5. HTML5 Mobile
  1. Node.js
  2. Debugging JavaScript
  3. OO JS
  4. JSON
  5. Ajax