I've learned to leave comments that explain what my line of thought was when I wrote the code in the first place. When you revisit your code after a months/years and see something weird or unusual and the comments don't give you a clue as to what you were thinking at the time, then it takes a while to figure things out and you might simply discount the code as crack smoking craziness. I will even indicate that I was in a rush or under high stress if I write something that might be confusing later so I will know it was not a conscious decision to hack something instead of taking time to work it out. Good comments don't pay off in the short term but they can certainly pay off in shovelfuls when you go to fix a bug.
I just write my scripts in all-comments first and then insert the actual code, I don't think there is a better mo for me personally, no matter how much time I got.
If I have a hard time to write the comment what this function is doing then it indicates that the function is written incorrectly.
My end-goal is to have self documenting code. I design the code so that it helps intellisense. This removes comments-blocks from the code and you don't get distracted with comments noise that basically says the same thing as the real code.
If logging is used then I use the logging as the comment alternative. The logging should say what the code does.
5 comments
2 u/Morbo 26 Aug 2016 02:06
I've learned to leave comments that explain what my line of thought was when I wrote the code in the first place. When you revisit your code after a months/years and see something weird or unusual and the comments don't give you a clue as to what you were thinking at the time, then it takes a while to figure things out and you might simply discount the code as crack smoking craziness. I will even indicate that I was in a rush or under high stress if I write something that might be confusing later so I will know it was not a conscious decision to hack something instead of taking time to work it out. Good comments don't pay off in the short term but they can certainly pay off in shovelfuls when you go to fix a bug.
1 u/xaric 25 Aug 2016 19:35
In such a way that it fixes itself when a bug is encountered.
1 u/saintPirelli 26 Aug 2016 09:06
I just write my scripts in all-comments first and then insert the actual code, I don't think there is a better mo for me personally, no matter how much time I got.
1 u/roznak 28 Aug 2016 01:39
I do it 2 ways.
If I have a hard time to write the comment what this function is doing then it indicates that the function is written incorrectly.
My end-goal is to have self documenting code. I design the code so that it helps intellisense. This removes comments-blocks from the code and you don't get distracted with comments noise that basically says the same thing as the real code.
If logging is used then I use the logging as the comment alternative. The logging should say what the code does.
1 u/alexkobold 29 Aug 2016 04:11
Given indefinite time you could write code to be so straightforward that no comments are needed.