Scribd
Upload
77 views2 pages

3 Common Kinds of Unnecessary Code Comments: Nickleus Jimenez August 2020

The document discusses 3 common types of unnecessary code comments: 1) Chronicle comments that narrate code history changes but source control serves this purpose better. 2) Lingering TODO comments that remain unchanged and unfinished for a long time. 3) Redundant comments that restate what is obvious from the code itself, such as method names and parameters. The conclusion recommends using source control instead of history comments, setting deadlines for TODOs, completing TODOs before code review, and prioritizing readable code over explanatory comments.

Uploaded by

Nickleus Jimenez
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
77 views2 pages

3 Common Kinds of Unnecessary Code Comments: Nickleus Jimenez August 2020

The document discusses 3 common types of unnecessary code comments: 1) Chronicle comments that narrate code history changes but source control serves this purpose better. 2) Lingering TODO comments that remain unchanged and unfinished for a long time. 3) Redundant comments that restate what is obvious from the code itself, such as method names and parameters. The conclusion recommends using source control instead of history comments, setting deadlines for TODOs, completing TODOs before code review, and prioritizing readable code over explanatory comments.

Uploaded by

Nickleus Jimenez
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 2

3 Common kinds of unnecessary Code Comments

Nickleus Jimenez

August 2020

[Software Engineering,.Net context]


Commenting code may be needed to convey information to teammates but some information are better
stated elsewhere.

1 Introduction
This is a listing of complaints of comments on code. Comments are needed from time to time but
great programmers make code that humans can read. Comments being needed is usually a bad sign.
Some comments are last resort in explaining convoluted code or algorithm. The times when they
are not a bad sign are legal disclaimers, ownership and design patterns reference. The times they
are frustrating as when they are used to chronicling comments history, show TODO that never gets
started and comments that are already explained in code There are other frustrating comments such
as misleading ones but those 3 will be the focus here.

2 Chronicle or journal Comments


Comments that narrates history of changes of the file just makes the file larger in a time where source
control should be available. Example is ”/* May 5 2020 Added if condition for empty string case of
parameter CategoryName */”. Those comments will pile up over time. Those comments will just cost
more Kilobytes. Source control is better cause of functionalities such as code history check, compare
and ability to revert. Bloating the source code serves no purpose. Even the intent of the changes can
be stated in the commits before pushing the changes.

3 Lingering TODO comments


”TODO” is not annoying at first but it can be alarming if the same ”TODO” comments is unchanged
long term or when the source code gets filled with them. The long term presence is a sign that
things are not completed nor started. There is a routine to search for ”TODO” on the source code to
measure unfinished work. Chances are there are ”TODO” that nobody starts possibly due to being
not required or no assigned which makes the tag ”TODO” questionable. Another possibility is that
the comments are ignored during code review and further development. A lot of times ”TODO” is
commented indicating for something to be done later but linger blank for a long time. Work items
with assignments for TODO found is a suggestion so that someone will start the so called ”TODO”
part.

4 Redundant Comments
Redundancy of comments is not limited to comments that have the same meaning as a previous com-
ment and excessive repeated explanation. It also includes comments that are better explained in code
like methods/functions/subroutines variables whose names should indicate its purpose. Commenting
”Gets the surname of person” of method ’GetSurname(Person givenPerson)’ looks so redundant when
the name of the method and parameters explains itself as it should. It is better to explain in code or

1
make code more understandable to the point of comments not being needed to explain other developers
what is going on. Exposition comments should be last resort of explaining intent. Complicated algo-
rithms or routines are still possible and explanatory comments are for that. These kinds of comments
are common in projects where mandating comments trumps over making readable code.

5 Conclusion
These 3 are common bad or improper comments seen in professional source codes. Some of these
can be symptoms of inadequate tools, pointless process or excessively lenient code review. Note that
comments is not the only way to evaluate code. Commenting is something that is needed but not that
well thought of which can eventually lead of misunderstandings and junk information like all other
bad documentation practices. So avoid those practices with having source control, setting deadlines
for To Do comments , finish ”TODO” before code review and make code as readable as possible before
thinking about explaining with comments.

You might also like