3 ms·

I could have written this article myself. For me, it is simple. Code maintainability is of paramount importance, and you've got all the history in the version

I could have written this article myself. For me, it is simple. Code maintainability is of paramount importance, and you've got all the history in the version control anyways. Comment is not Code. They are written for humans for maintaining the program, where as code is written for machine to execute. No code should be commented. Ever* . Comments should only contain text in english (or what ever language you + your collaborators/people you have to maintain the code in future speak.) * Well, Unless you are not using Version control, which is criminally bad. There is absolutely no reason to not use version control.

hdragomir 15y ago
Bingo!
chrislomax 15y ago
I disagree with this. I actually comment out code to show what the end result would be. If have a piece of code that iterates over to create the json to make a gallery object. I have done what the json end result should look like and commented it out so if anyone comes back in future they can see what I have done and why I have done it. I suppose you could argue that the code example is a comment but it is code at the end of the day
- random42 15y ago
  Why not actually write an example (like a short blog post, containing some code snippets), in the comment, using the native language, instead of commenting the live code? Dont you think it would improve the readability of the code? Sure it takes slightly more time, (may be 10 extra mins, for a small example), but I can assure you, a newbie, who is new to the codebase/language, would certainly appreciate such an example. (I know, I would have.)
  - chrislomax 15y ago
    I do it because its inline. If someone is looking over the code and right above the recursion see's an example of what I am doing in my eyes makes it more readable. Don't get me wrong, it's not something I do every day, I may have done it 3 or 4 times in my life but I have done it. I mainly do it for debugging purposes. If you are stepping through and you can see a string example of the output you can instantly compare it to your built string of JSON. I am probably just being pedantic but I can see a use for commenting certain code. If i blog posted it and changed it then I would need to make an active effort to update the blog. It would be like maintaining documentation. I can just update the comment above and be on my way. I think everyone has their own methods and I'm not saying yours is wrong, I am just saying I do see a need to put code in comments sometimes. There are only two devs here though and we know what we are doing, if a noob came in then to be honest they wouldn't be touching my code until they understand it anyway
    - random42 15y ago
      > I am just saying I do see a need to put code in comments sometimes. Yup, There are rules, and then, there are rules. The important thing is to realize what practice makes sense, for the given condition... and why.

hdragomir 15y ago

Bingo!

chrislomax 15y ago

I disagree with this. I actually comment out code to show what the end result would be. If have a piece of code that iterates over to create the json to make a gallery object. I have done what the json end result should look like and commented it out so if anyone comes back in future they can see what I have done and why I have done it. I suppose you could argue that the code example is a comment but it is code at the end of the day

random42 15y ago
Why not actually write an example (like a short blog post, containing some code snippets), in the comment, using the native language, instead of commenting the live code? Dont you think it would improve the readability of the code? Sure it takes slightly more time, (may be 10 extra mins, for a small example), but I can assure you, a newbie, who is new to the codebase/language, would certainly appreciate such an example. (I know, I would have.)
- chrislomax 15y ago
  I do it because its inline. If someone is looking over the code and right above the recursion see's an example of what I am doing in my eyes makes it more readable. Don't get me wrong, it's not something I do every day, I may have done it 3 or 4 times in my life but I have done it. I mainly do it for debugging purposes. If you are stepping through and you can see a string example of the output you can instantly compare it to your built string of JSON. I am probably just being pedantic but I can see a use for commenting certain code. If i blog posted it and changed it then I would need to make an active effort to update the blog. It would be like maintaining documentation. I can just update the comment above and be on my way. I think everyone has their own methods and I'm not saying yours is wrong, I am just saying I do see a need to put code in comments sometimes. There are only two devs here though and we know what we are doing, if a noob came in then to be honest they wouldn't be touching my code until they understand it anyway
  - random42 15y ago
    > I am just saying I do see a need to put code in comments sometimes. Yup, There are rules, and then, there are rules. The important thing is to realize what practice makes sense, for the given condition... and why.