4 comments

• 

  Too shy to say my name.

  3 years ago

  Obvious comments do suck when you look at the code. However, sometimes (like just before negotiating your salary or vacation plans - or for some other personal or professional reason) you might want to use the javadoc tool to generate fancy and goodlooking API documents to show someone to prove, or create the illusion of, work well done! In this case the tagline "Never, ever, say in comments what the code already says." is not appliable as there is no code to look at, but only the generated API docs! I still agree that comments should not be verbose, but they should be there (even if they are slightly useless and redundant when you have the souce code in front of you). Keep them in dense form though.
  
  P.S. Wouldn't it be nice with a "do not show comments"-function in the IDE? Then we could have both clean code and nice API docs at the same time with no annoyance.
  
  P.S.S. Almost forgot; writing good code is just as hard as writing good comments. Some programmers are actually better at writing comments than code and in those cases having comments to read before rewriting their uncomprehensible code is nice.
  reply
• 

  Ole Christian Rynning

  3 years ago

  For object oriented languages I feel the class header should ALWAYS be commente.
  
  _Especially if the classname is a generic one like *HashTable_.
  
  One of many nuiances working with legacy code is figuring out in which context(s) classes are used and sometimes the mere purpose of them without reading through the entire class.
  
  If you call outside objects methods its useful to briefly tag them with a comment or even a @see doclet.
  reply
• 

  Kjetil

  3 years ago

  Too shy: just enable automatic code folding for comments in IntelliJ. Then you can unfold if you need a close look.
  reply
• 

  Marius Mårnes Mathiesen

  3 years ago

  I just stumbled across another piece of fantastic code comments that I'd love to share. It's from the PHPUnit2 documentation, have a laugh:
  
  protected function setUp()
  {
  // Create the Array fixture.
  $this->fixture = Array();
  }
  
  public function testNewArrayIsEmpty() {
  // Assert that the size of the Array fixture is 0.
  $this->assertEquals(0, sizeof($this->fixture));
  }
  
  public function testArrayContainsAnElement() {
  // Add an element to the Array fixture.
  $this->fixture[] = 'Element';
  
  // Assert that the size of the Array fixture is 1.
  $this->assertEquals(1, sizeof($this->fixture));
  }
  reply