DevEd 036: Comments DevEd

In this week's episode of the DevEd podcast, the panelists talk on comments in programming. To give a context of the chosen topic, Joe mentions that he sends out regular newsletters to Thinkser.io subscribers related to a variety of concepts, and has recently been sending out some on code smells, in one of which he talks about commenting. He gives an idea of what code smells are, and shares his opinion on using comments. His point of view is that a comment can be looked at as a failure or an inability to express the code functionality or even the technology involved, or is needed to make the code completely readable to other programmers. Comments can become out of date or get replaced.


The other panelists join in the discussion on whether comments are good or bad, and they state that for beginners they can be very useful while not so much for experienced programmers. Too many comments can cause a mess, so they ideally should be used for large complex functions. They are mostly used to specify if refactoring is needed at a later stage, they should explain the "why" instead of "how", and in general the code should ideally be self-sufficient.


They talk about when do they actually like to use comments. If a certain piece of code is doing something unusual or non-obvious or might break the consistency with the rest of the code, then it is imperative to explain why it is written that way. It can also be a good idea to document things for new or junior developers in the team in order to explain what is going on or what should not be done, and also to pair program with them in case things are not clear. Commit messages could be a replacement for comments as well. Comments are also useful when static values and constants such as URLs or UIDs are used in the code, and for explaining specific error mechanisms.


They share great practical advice for programmers who are in the earlier stages of their software development career and have generally been taught to use comments by their professors or mentors. The tips they give include taking time to look through the codebase, checking how and where comments are being used by other developers, refactoring the code to write more readable functions wherever things are unclear, using good naming conventions, trying to write self-documenting code, asking a lot of questions to whoever has written the code including asking the reasons why it is written a certain way, and not being afraid to add comments of your own.


They then discuss some replies to the newsletter sent by Joe about code smells related to the importance of comments in the messy reality of engineering, pros and cons of their usefulness, tradeoff between maintaining self-documented vs heavily documented code. They end the show with picks.


The DevEd podcast is produced by Thinkster.io and published by DevChat.TV.


Panel


Joe Eames
Jesse Sanders
Luis Hernandez
Preston Lamb
Mike Dane


Sponsors


Thinkster.io
The Freelancers' Show
React Round Up
CacheFly


Picks

Luis Hernandez:



Sourcetree


Mike Dane:



Google Fi


Preston Lamb:



Office Ladies podcast


Jesse Sanders:



Tesla cars


Joe Eames:



Gaslands


Question #1: What are code smells?


A pattern that indicates that there may be a problem in the code with a possibility of improvement.


Question #2: When should comments be used?


Comments could be useful for beginners, not so much for experienced folk. Too many comments can cause a mess, so they ideally should be used only for large complex functions. They can be used to specify if refactoring is needed at a later stage, and for explaining the "why" instead of "how".


Question #3: What are some good reasons to use comments?


1. If a certain piece of code is doing something unusual/non-obvious/might break the consistency with the rest of the code. 2. For new or junior developers on the team in order to explain what is going on or what should not be done. 3. When using static values and const