4 ms·

This seems wrong to me. If the "why" is not obvious from the code itself then it should be clearly explained in comments. It should not be detective work to fig

by olavk 8y ago

This seems wrong to me. If the "why" is not obvious from the code itself then it should be clearly explained in comments. It should not be detective work to figure out why some code is written in a non-obvious way. Otherwise people will be afraid to improve code.

masklinn 8y ago
> If the "why" is not obvious from the code itself then it should be clearly explained in comments. Except you can't trust comments. Even assuming the comments were relevant at one point, they don't get updated as the code changes, and as new code gets added they can drift away from the original code they were supposed to explain. Commit messages don't drift, they're immutably bound to the changes the commit performs. And because they're not bloating up the code it's much easier to be clear and verbose in commit messages than it is in comments, the author can easily explain things which seem obvious to them but may not be so for a reader in a few months or years without lowering the overall readability of the code which is not the case of comments. People will criticise comments as "obvious" and "unnecessary", I've yet to have a colleague or contributor criticise a detailed commit message for any other reason than the commit message being wrong. > It should not be detective work to figure out why some code is written in a non-obvious way. Get proper tools. Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory.
- cesarb 8y ago
  > Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory. That works until the VCS history is lost. For an on-topic example, this usually happens when a formerly closed-source code is released to the public: only the final state of the source code is released, with none of the VCS history. This can also happen when changing to another VCS; often the history is kept only on the former VCS. Some projects have gone through several of these events; I challenge you to find early StarOffice history when trying to understand why some piece of LibreOffice code is written that way. And there's also the tendency in some places to reference bug tracker issues in commit messages. Said bug trackers tend to have an even shorter life than the VCS. "Fixes issue #1234" is useless when issue 1234 was on the old bug tracker, and both it and the new bug tracker were lost when the company was acquired and migrated to a third bug tracker.
- olavk 8y ago
  Comments may drift if the code is not maintained properly, but commit messages will also drift. The more you edit/move/refactor, the harder it will be to connect the code in question with the relevant commit message. I don't believe good tools will save you here - the more changes happen to the code, the harder it will be to find the relevant commit message which explains the code. Comments you can at least make an effort to keep up to date. Especially if have a policy that all comments should actually be relevant. Comments shouldn't be obvious and unnecessary. They should explain things which cannot be inferred from the code itself, eg, // have to call reset() twice here because the XZW API has a bug which restarts the server if reset is not called twice. See ...

by olavk 8y ago

masklinn 8y ago

> If the "why" is not obvious from the code itself then it should be clearly explained in comments. Except you can't trust comments. Even assuming the comments were relevant at one point, they don't get updated as the code changes, and as new code gets added they can drift away from the original code they were supposed to explain. Commit messages don't drift, they're immutably bound to the changes the commit performs. And because they're not bloating up the code it's much easier to be clear and verbose in commit messages than it is in comments, the author can easily explain things which seem obvious to them but may not be so for a reader in a few months or years without lowering the overall readability of the code which is not the case of comments. People will criticise comments as "obvious" and "unnecessary", I've yet to have a colleague or contributor criticise a detailed commit message for any other reason than the commit message being wrong. > It should not be detective work to figure out why some code is written in a non-obvious way. Get proper tools. Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory.

cesarb 8y ago
> Browsing annotations and reading commit messages is not "detective work", it's absolutely straightforward and means you're actually using your VCS as something more than a glorified tarballs directory. That works until the VCS history is lost. For an on-topic example, this usually happens when a formerly closed-source code is released to the public: only the final state of the source code is released, with none of the VCS history. This can also happen when changing to another VCS; often the history is kept only on the former VCS. Some projects have gone through several of these events; I challenge you to find early StarOffice history when trying to understand why some piece of LibreOffice code is written that way. And there's also the tendency in some places to reference bug tracker issues in commit messages. Said bug trackers tend to have an even shorter life than the VCS. "Fixes issue #1234" is useless when issue 1234 was on the old bug tracker, and both it and the new bug tracker were lost when the company was acquired and migrated to a third bug tracker.
olavk 8y ago
Comments may drift if the code is not maintained properly, but commit messages will also drift. The more you edit/move/refactor, the harder it will be to connect the code in question with the relevant commit message. I don't believe good tools will save you here - the more changes happen to the code, the harder it will be to find the relevant commit message which explains the code. Comments you can at least make an effort to keep up to date. Especially if have a policy that all comments should actually be relevant. Comments shouldn't be obvious and unnecessary. They should explain things which cannot be inferred from the code itself, eg, // have to call reset() twice here because the XZW API has a bug which restarts the server if reset is not called twice. See ...