I find it interesting how controversial the code comments situation has become.
When I started in this industry, comments were extremely rare and people were consistently pushing to add comments everywhere. Some time later, the pushback came and people started saying that code shouldn't need comments, and if you feel the need to add one... You should rewrite it instead so the code is self explanatory.
Neither side seems to have stopped repeating their points though and there is always a chance to trigger opinionated people into endless discussions just by mentioning comments
One big thing that has changed in regard to comments is that variables and functions can have longer names now. In most modern languages it is considered bad practice to have single letter variables, or even abbreviated ones, except in very well known cases.
So the rule of thumb for languages like python or ruby is that if you need comments to understand what your code is doing, then you messed up somewhere. Make it easier to read, keep your functions small, and add docstrings. Save your comments for why you're doing something.
But if you're using a less readable language like c, then by all means, comment everything along the way.
I just read a comment I wrote a few years ago that said "I don't know why I have to do it the long way, but it's the only thing that works consistently" over a bit of seemingly verbose code that I would have tried to simplify if I didn't remind myself of that previous struggle.
In the previous century I worked at a company that offered a SQL database, and the mandatory coding standard included:
- Maximum of six characters for any function name. Three characters for the category and three for the actual function. Imagine a code base where every function has a name like strcmp, strlen, etc. So you might have a name like sqlijn for an inner join.
- 80 column line limit, with the first 40 columns reserved for code, and the second 40 columns for a comment. A comment was required on every line of code. So yes indeed, you might see this classic:
++i; /* increment i */
I was hired to build a Windows GUI for the database, and I explained that Windows API functions had much longer names and I was going to run out of room to do much in 40 columns. Thankfully, they gave me special dispensation to follow Windows conventions in the Windows code.
The trouble with comments is that good taste as well as intelligence is required of the comment author. If you cast your mind over your colleagues you see the problem.
SELECT
CAST(CASE WHEN DENY_ADMIN_FILTERS > 0 THEN 0 WHEN ALLOW_ADMIN_FILTERS > 0 THEN 1 END AS bit) CAN_ADMIN_FILTERS,
CAST(CASE WHEN DENY_ADMIN_ACL > 0 THEN 0 WHEN ALLOW_ADMIN_ACL > 0 THEN 1 END AS bit) CAN_ADMIN_ACL,
CAST(CASE WHEN DENY_ADMIN_RML > 0 THEN 0 WHEN ALLOW_ADMIN_RML > 0 THEN 1 END AS bit) CAN_ADMIN_RML,
CAST(CASE WHEN DENY_ADMIN_WORKFLOW > 0 THEN 0 WHEN ALLOW_ADMIN_WORKFLOW > 0 THEN 1 END AS bit) CAN_ADMIN_WORKFLOW,
CAST(CASE WHEN DENY_SET_STATE > 0 THEN 0 WHEN ALLOW_SET_STATE > 0 THEN 1 END AS bit) CAN_SET_STATE,
CAST(CASE WHEN DENY_SHARE > 0 THEN 0 WHEN ALLOW_SHARE > 0 THEN 1 END AS bit) CAN_SHARE,
CAST(CASE WHEN DENY_LINK_PARENTS > 0 THEN 0 WHEN ALLOW_LINK_PARENTS > 0 THEN 1 END AS bit) CAN_LINK_PARENTS,
CAST(CASE WHEN DENY_UNLINK_PARENTS > 0 THEN 0 WHEN ALLOW_UNLINK_PARENTS > 0 THEN 1 END AS bit) CAN_UNLINK_PARENTS,
CAST(CASE WHEN DENY_LINK_CHILDREN > 0 THEN 0 WHEN ALLOW_LINK_CHILDREN > 0 THEN 1 END AS bit) CAN_LINK_CHILDREN,
CAST(CASE WHEN DENY_UNLINK_CHILDREN > 0 THEN 0 WHEN ALLOW_UNLINK_CHILDREN > 0 THEN 1 END AS bit) CAN_UNLINK_CHILDREN,
CAST(CASE WHEN DENY_WRITE > 0 THEN 0 WHEN ALLOW_WRITE > 0 THEN 1 END AS bit) CAN_WRITE,
CAST(CASE WHEN DENY_SEE > 0 THEN 0 WHEN ALLOW_SEE > 0 THEN 1 END AS bit) CAN_SEE,
CAST(CASE WHEN DENY_READ > 0 THEN 0 WHEN ALLOW_READ > 0 THEN 1 END AS bit) CAN_READ,
CAST(CASE WHEN DENY_READ_END > 0 THEN 0 WHEN ALLOW_READ_END > 0 THEN 1 END AS bit) CAN_READ_END
FROM
private_data_iviews.SECURITY_PRECACHE_ACL_INCLUSIVE WITH (NOEXPAND)
WHERE
@acl_id IS NOT NULL
AND @acl_id = ACL_ID
AND @user_id = USER_ID
This seems like a good example of when not to arbitrarily align characters. Large horizontal gaps can very easily result in moving up or down a line and not realizing it.
When you hardcode a lookup table to be able to align data is very useful (and also esthetically pleasant), at least from my point of view. I would not leave my monospace font
Add a few more parameters, put some arithmetic in there that isn't clearly an unrolled double for-loop. Maintaining repetitive code of that form is easier when the arguments are well aligned. And if you're using an editor with a block-select feature, then this changes from an aesthetic preference into a game-changer when you, say, add or remove an argument to foo.
Printing a table to the console or log file. A very simple example from just this weekend for me is that I wanted to see how C++ was laying out an object in memory. I assigned the pointers to one and two character variables. When I printed out the variable name followed by the address, I actually had to go back and add an extra space before the single character variable names so the addresses would align. That made it much easier to see the differences between the various pointers into the object.
Funny you mention log files with extra spaces. At my current job, I deal with an API called the RTO, and I wanted to log the requests to that API and the matching responses.
Of course the words "request" and "response" are not the same length. But I thought it would look nice to line things up for a request and its matching response, so I just added an extra space after "request:", like this:
RTO request: {...}
RTO response: {...}
When testing locally in a terminal, this looked great. Everything lined up and was pretty.
What I didn't realize was that most people view these logs in New Relic, which does use a monospaced font but does not prevent collapsing of adjacent spaces. So the logs look like this:
RTO request: {...}
RTO response: {...}
Obviously not the end of the world! But it did happen that the first part of the {...} stuff should match between the request and the response, so it made it easier to understand (if it worked) to line them up.
I am tempted to change the messages to this, which I think will work around this problem:
Or I will say "yup, you got me there!" ;-)