6 ms·

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 comment

by herbst 10y ago

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.

sehr 10y ago
Any examples? That sounds like it might get awkward when it comes to reuse.
- herbst 10y ago
  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.
hellofunk 10y ago
No one wants to look through a lengthy git log to find the reason something was done to a particular block of code!
- mattferderer 10y ago
  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.
- herbst 10y ago
  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.
  - michael_h 10y ago
    Half of the time, when I look at the git blame for a certain line, I get: 'whitespace-only change'
almata 10y ago
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?
- herbst 10y ago
  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.
  - wruza 10y ago
    >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.
- xapata 10y ago
  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.
lallysingh 10y ago
Sounds like you learned how to code, but not how to engineer software.
- herbst 10y ago
  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.
Walkman 10y ago
It's interesting what you say, because I sometimes don't know when a particular comment should go into code or commit message!
- herbst 10y ago
  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.
deleted 10y ago
[deleted]

by herbst 10y ago

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.

sehr 10y ago

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

herbst 10y ago
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.

hellofunk 10y ago

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

mattferderer 10y ago
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.
herbst 10y ago
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.
- michael_h 10y ago
  Half of the time, when I look at the git blame for a certain line, I get: 'whitespace-only change'

almata 10y ago

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?

herbst 10y ago
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.
- wruza 10y ago
  >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.
xapata 10y ago
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.

lallysingh 10y ago

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

herbst 10y ago
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.

Walkman 10y ago

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

herbst 10y ago
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.

deleted 10y ago

[deleted]