• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Troubleshooting Java: Read, debug, and optimize JVM applications: importance of inline documentation

 
Greenhorn
Posts: 19
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
As a frequent reviewer of code, I often find myself moaning about the lack of comments and general inline documentation (javadocs also).

To assist with reading code, what's your take on the importance of documentation ""in the code", or do you also buy the excuses:

  • Java is self-documenting, it doesn't need comments
  • Comments could get out-of-date then it would be worse than not having them
  • Comments could be wrong, so I always have to read the code anyway
  • It's only ... (test, PoC, temporary) code so why bother
  • I didn't have time!

  • I'd love to know your thoughts!
    Kind regards,
    YoungJules
     
    Marshal
    Posts: 79179
    377
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    Julian Isaac wrote:. . .

  • Java is self-documenting, it doesn't need comments
  • . . .

    Code is only self‑documenting if you follow the principles of writing straightforward code.
    Round here we see the opposite problem. Beginners are told to document everything they do, so we see this sort of thing:-When you get that sort of comment, it ceases to be an explanation and becomes clutter.
     
    Julian Isaac
    Greenhorn
    Posts: 19
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    Yeah, I get that. That's why I often ask for developers to document the why, not the what.

    // Now increment idx by 1
    idx++;

    Might become

    // Skip over the length byte
    idx++;

    But indeed there is an argument for not documenting the bleedin' obvious, so long as we allow for the fact that what's obvious to some of the smarter devs on my team may not be so obvious to all the devs, or even to me  
     
    Campbell Ritchie
    Marshal
    Posts: 79179
    377
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    Julian Isaac wrote:. . . Might become

    // Skip over the length byte
    idx++; . . .

    And that might become,

    // The next byte is the length byte
    idx++;

    Not sure which version is clearer.
     
    Julian Isaac
    Greenhorn
    Posts: 19
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    The point was not really to zoom in on a specific comment to determine the most perfect clarity, but just to make the general observation, perhaps useful for newbies, that it's better to say WHY you're doing something in the code, rather than WHAT you're doing.

    I'm still eager to hear the author's take on the importance of comments when it comes to reading code...
     
    Dinner will be steamed monkey heads with a side of tiny ads.
    a bit of art, as a gift, the permaculture playing cards
    https://gardener-gift.com
    reply
      Bookmark Topic Watch Topic
    • New Topic