An Interest In:
Web News this Week
- April 20, 2024
- April 19, 2024
- April 18, 2024
- April 17, 2024
- April 16, 2024
- April 15, 2024
- April 14, 2024
About code comments
Documentation and comments serve a similar purpose. It is about communicating to other developers now, to other developers in the future and also to yourself in the future.
When I am talking about comments, I am not talking about comments used to document an API, functions, classes or modules. These are not really comments but rather inline documentation.
In this Article I am talking about comments but also check out my article on documentation.
Comments
Code comments have a really bad reputation and there is a good reason for it.
Comments, just like documentation, lie really quickly. Most often because they get outdated and are not updated.
Often, they only state the obvious and this just clutters the code.
#loop through the values to be checkedwhile i <= maxNum: [...]
For this reason, a lot of people have outlawed comments and will not comment their code at all. I understand this but still comments have a really good use and I like to make a case for using them sparingly.
Do not use comments if not necessary
Sometimes better names make comments redundant and even improve the code because using the name always carries the meaning.
let price = 0; // price in cents
vs
let priceInCents = 0;
Often, comments are used to structure code. For structure we have better tools that never lie.
function processInput(input: string) { // validate input if (input.length < 10) { throw "input too short" } if (input.length > 100) { throw "input too long" } // remove colors let result = input.replace('red', '').replace('green', '').replace('blue', ''); // format result result = result.trim().toUpperCase() return result }
If we just take the comments and make them into functions, the code is even more clear. You don't even have to look at the implementation details if you do not care at this point in time. It can also be used to contain ugly and unclear implementations (sometimes it is just not avoidable).
function processInput(input: string) { validateInput(input); let result = removeColors(input); return formatResult(input) }function validateInput(input: string) { if (input.length < 10) { throw "input too short" } if (input.length > 100) { throw "input too long" }}function removeColors(input: string) { return input.replace('red', '').replace('green', '').replace('blue', ''); } function formatResult(result: string) { return result.trim().toUpperCase(); }
The above code very clearly shows the 3 responsibilities of the processInput
function. validate, do and return formatted. I do not want to make the point that you always have to structure your functions this way. Often, having the validation inside the "mother" function is a good idea to show exactly what is going on. But when you feel the urge to write a comment to structure code, think about using a function for structure.
Use comments to explain the why, the odd and the consequences
What we, more often than not, can not illustrate with code structure is the why, the odd and the consequences of something. Everytime something would surprise you in a year or a new developer, this is a very good reason to introduce a comment.
the why
// we are moving between API's so we are calling new and old apis.oldUsersApi.updateData(userData);newUserApi.updateData(userData);
the odd
// this is odd but the 3rd party client api enforces us to disconnect before we can connectclient.disconnect()client.connect()
the consequences
user.delete() // deleting the user will cascade deletion of all their data
My guidelines for commenting code well
- Only comment the why and only if not obvious
- Always try to explain yourself in code first.
- Use as explanation of intent.
- Use as clarification of code.
- Use as warning of consequences.
This article is extracted from a series of talks I gave.
Original Link: https://dev.to/jgroeneveld/about-code-comments-27ml
Dev To
An online community for sharing and discovering great ideas, having debates, and making friendsMore About this Source Visit Dev To