Hacker News Reader

Comment by herbst | Hacker News Reader

I learned to code in a way that the variable and function names also would tell you the why. And otherwise the git log is your friend.

Tl:dr; i only do comments to excuse really stupid code.

View on HN

No one wants to look through a lengthy git log to find the reason something was done to a particular block of code!

Visual Studio Pro & up has a great feature that puts a tiny snippet of text above each class & method that says the last author, how many authors & how many changes have been done on that specific class or method. You can hover over this text and see a box with a scroll bar that shows you the commits & comments that changed the class or method.

I'm not sure if any other IDE or editors have this but I really love this feature as a method of documentation. I'm not saying it is the best method or the only method one should use, just a useful method that I wish more IDEs & editors had.

I assume every damn editor out there has a plugin that makes this a complete non issue. I spend most of my time in a terminal anyway and know my way around it, i prefer it by far to comments, also because of the metadata like dates and authors which rarely is found in comments.

Half of the time, when I look at the git blame for a certain line, I get: 'whitespace-only change'

Isn't a short comment a much quicker method to get why something has been done that way instead of having to check git log? Also, if you rely on git log for that, don't commit messages become unnecessarily long and detailed?

no, that rarely happens. There are plugins where you can run git blame within your text editor by marking text. It is like you have a comment but without making the code more messy as it only shows with a "click".

Another point is that people tend to write awful comments anyway.

>Another point is that people tend to write awful comments anyway.

This. When we talk about stellar teams with stellar writers both in programming language and english, it seems nice to throw comment here and there. But when I look at what we do at work, I just... want to s{//.+$}{}, because comments there are A) misleading, B) senseless, C) grammatically awful, D) obsolete. Today almost everyone can be a programmer, but only few know how to explain things in short text at right place. You have to be writer to do that.

The best way to test a comment is to turn it into code and test it as code. Or, in more modern way, make a neural network that parses comments and check if these apply.

Commits should be long and detailed, though the details for the commit log are for a different purpose. In the commit logs I want to know why the change was developed -- what issue it fixed, what feature request it implements. I want the code comments to explain the logic of a large chunk of code, at a higher level than just reading line by line.

Any examples? That sounds like it might get awkward when it comes to reuse.

Given we are a small team and know each others typical structures. It also helps that i only did this in a MVC environment, so structure was given mostly.

I dont want to link to company applications honestly, and my personal ones are way to messy in terms of inline documentation anyway.

Sounds like you learned how to code, but not how to engineer software.

Thats a bit much to suspect based on a single sentence don't you think?

I am sure there are environments where this would be super messy, but if you work in small teams in a given structure always following best practice and basic refactoring. 99.9% of the code gets pretty obvious in its use.

It's interesting what you say, because I sometimes don't know when a particular comment should go into code or commit message!

If you would work in the company i worked (e-gov in switzerland) comments are strongly discouraged (except as said if you do something stupid and you expect the reviewer to notice and give some inputs).

My rule is like: Make the code say what it does, if you have to explain why it does what it does do it in the commit message.

Reply on news.ycombinator.com