{CodingBlocks}.NET

iTunes Spotify PlayerFM Overcast Podchaser Pocket Casts iHeartRadio YouTube feed LinkedIn Twitter Facebook Reddit

Navigation

Clean Code – Comments Are Lies

By 41 Comments

Podcast: Play in new window | Download

Subscribe: Apple Podcasts | Spotify | TuneIn | RSS

This week, Michael fails geography, Allen introduces us to Croom, and Joe has to potty as we head into our third installment of the Clean Code series.

Want to be part of our Slack community? Sign up @ https://www.codingblocks.net/slack and say “hi”!

Join the Slack

Link to Episode 49’s Full Show Notes

https://www.codingblocks.net/episode49

Survey

Do you put stickers on your laptop?
vote
×

News

Stickers! Stickers All the Things!

Want some Coding Blocks stickers? Send us a self-addressed stamped envelope and we’ll send you some of the most amazing stickers you’ve ever seen.

Comments

  • “At best, comments are a necessary evil”
  • “The purpose of a comment is to compensate for our failure to express ourself in code”
  • Try to express yourself in code rather than a comment
  • Comments should be updated as code is updated, but a better use of time would be to make the code itself more expressive
  • Inaccurate comments are worse than no comments at all – they’re lies…misleading
    Comments do NOT make up for bad code
  • If you feel you need to comment the code, it might be a good time to assess whether you should create a new method that will better express what you’re attempting to do
  • “The only good comment is the one you found a way not to write”
  • Copyright and licensing are good uses of comments – they’re usually required
  • These comments should provide a reference to the full body of the license rather than including the text in the comment
  • Another good use shown in the book is showing the expected format of a regular expression
  • Clarifying comment to describe what you’re doing when working with a third party library you cannot change is also useful at times – this can be tricky because you could make bad assumptions and misinform – so take caution
  • TODO – sometimes ok, but don’t want them to litter up your repo
  • Documentation for public API’s – just be careful not to write non-truths here as it’s easy to do if you don’t update your comments as the code changes
  • Most comments are just bad comments…not needed and code should have been changed
  • Took some shots at Javadocs for Tomcat – they were admittedly pretty useless
  • Too easy to write misleading comments – subtle differences can lead people down the wrong path
  • Author generally dislikes commenting of methods – for the fact that they will eventually become misleading if not so at the outset
  • Log journals – used to be useful before source control – now they should be removed – SQL anyone?!
  • Noise – useless, add nothing comments – restating the obvious
  • Comments that complain about things are bad – they should be refactored into useful methods
  • Don’t use a comment when you can use a function or variable
  • Banners – used to identify a section in code – can be useful but also lose effectiveness if overused
  • Don’t put your bylines in the code- let the source control keep track of that for you
  • Do NOT comment out code…delete it – source control will provide you a history
  • HTML Comments in your code should NOT be used…it’s unreadable
  • Only comment on the code right next to the comment – do not make system type of comments as they can quickly become incorrect
  • Don’t write too much information in a comment
  • The comment should be easy to connect to the code it’s describing – if it doesn’t then the comment is worse than useless
  • Function headers – a well named function is better than a comment header
  • Only use Javadocs (or similar) for public API’s – they do more harm than good in private repos

Resources We Like

Of course we’re going to mention Clean Code by Robert C Martin here, right? Yes, yes we are. Want a copy? Comment on this show for your chance to win a copy!

Clean Code

Clean Code

Tip of the Week

  • Add a path to your Git commands to narrow their scope:
    • git status [path]
    • git diff [path]
    • git add [path]
  • http://hyperdev.com – Focus on building your MVP. Not the infrastructure.
  • http://www.codemaid.net/documentation/ – Don’t just read about clean code. Use some tools to keep it clean!

Enjoyed the Show? Tell Everyone!

Do you like us? Pick one:

– Yes
– Of course!
– Um, yeah, but this is weird.

 

So then you should tell everyone. And I’m mean everyone. And when you’re friends ask what you’re doing? Answer: Coding Blocks! When your boss asks how you’ve suddenly gotten more productive? Answer: Coding Blocks! And when mom asks what you want for dinner? Answer: Tacos! Er, wait. Well, you get the idea. Spread the word.

And by the way, if you haven’t already, head over to www.codingblocks.net/review to leave a review as your digital way of shouting from the roof tops how much you enjoy the show.

Peace, love, and Coding Blocks.

Share the joy