4 ms·

I never said I didn't have version control. To assume "at the code level it should be largely self-documenting" is to be a Rick. Comments are there to help eve

I never said I didn't have version control. To assume "at the code level it should be largely self-documenting" is to be a Rick. Comments are there to help everyone, including non-programmers understand what is going on.

skinnymuch 9y ago
You said initially companies have their tools and you don't. Later you went on about simply using ftp and coding php. It sure seems like you don't use version control. At least not at a level that it should be used at in this day and age.
sverhagen 9y ago
What am I to make from: "while I know companies use tools to do their thing... I don't", if not that you're not using a version control tool? It's not "genius behavior", but well accepted from people like Uncle Bob, that documentation should be in the names of small and focused functions, methods or classes, not in comments.
debaserab2 9y ago
> To assume "at the code level it should be largely self-documenting" is to be a Rick You don't have to be a Rick to write clean, concise code. I'd strongly recommend reading up: http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-Used-To-Comment-Code-and-What-To-Do-About-Them/2293 http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-U... https://blog.codinghorror.com/coding-without-comments/ https://blog.codinghorror.com/coding-without-comments/
valuearb 9y ago
I have been coding for almost 40 years and always been big on documenting code, but the problem is that code changes and documentation doesn’t always keep up. Given modern tools I’ve come to the conclusion that documenting overall purpose and specific edge cases is more than enough. For example, the file header should describe its purpose, and anything in the actual code that’s not obvious should be commented. No more boilerplate function or file comment header. Git tells me who wrote each line of code, I know the name of the funcs and files, and I can see the inputs/outputs for every func with my own two eyes.
- sgift 9y ago
  > I have been coding for almost 40 years and always been big on documenting code, but the problem is that code changes and documentation doesn’t always keep up. This has always been a sign for me to tread very, very carefully. People who change code without changing the comments probably didn't read the comments, didn't read the code or didn't understand it - either way, if comment and code disagree both are probably wrong.
  - valuearb 9y ago
    I agree mismatched comments/code is a huge warning sign. But I think requiring standardized comments is a problem. When I started out every function had to have a header comment, with name, inputs/outputs, description of purpose/etc. It was significant extra work to keep that up to date. I could update a function three times in a day, and have to rewrite the comments three times to check it in. And in the end, I know the name of the function. I can see the inputs and outputs. The only part of those comments that were occasionally useful were purpose, details of which often changed with edits. And in reality, as long as the function isn't hundreds of lines long (another problem), I can read it and discern exactly what it's trying to do. Comments that were most useful said stuff like "this looks weird or dumb, but we had to do it this way because of this thing we and you probably didn't expect in the data/system/etc"
pc86 9y ago
For what logical purpose would a non-programmer be reading your source code and only be able to accomplish whatever their task is if you adequately comment it?

skinnymuch 9y ago

You said initially companies have their tools and you don't. Later you went on about simply using ftp and coding php. It sure seems like you don't use version control. At least not at a level that it should be used at in this day and age.

sverhagen 9y ago

What am I to make from: "while I know companies use tools to do their thing... I don't", if not that you're not using a version control tool? It's not "genius behavior", but well accepted from people like Uncle Bob, that documentation should be in the names of small and focused functions, methods or classes, not in comments.

debaserab2 9y ago

> To assume "at the code level it should be largely self-documenting" is to be a Rick You don't have to be a Rick to write clean, concise code. I'd strongly recommend reading up: http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-Used-To-Comment-Code-and-What-To-Do-About-Them/2293 http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-U... https://blog.codinghorror.com/coding-without-comments/ https://blog.codinghorror.com/coding-without-comments/

valuearb 9y ago

I have been coding for almost 40 years and always been big on documenting code, but the problem is that code changes and documentation doesn’t always keep up. Given modern tools I’ve come to the conclusion that documenting overall purpose and specific edge cases is more than enough. For example, the file header should describe its purpose, and anything in the actual code that’s not obvious should be commented. No more boilerplate function or file comment header. Git tells me who wrote each line of code, I know the name of the funcs and files, and I can see the inputs/outputs for every func with my own two eyes.

sgift 9y ago
> I have been coding for almost 40 years and always been big on documenting code, but the problem is that code changes and documentation doesn’t always keep up. This has always been a sign for me to tread very, very carefully. People who change code without changing the comments probably didn't read the comments, didn't read the code or didn't understand it - either way, if comment and code disagree both are probably wrong.
- valuearb 9y ago
  I agree mismatched comments/code is a huge warning sign. But I think requiring standardized comments is a problem. When I started out every function had to have a header comment, with name, inputs/outputs, description of purpose/etc. It was significant extra work to keep that up to date. I could update a function three times in a day, and have to rewrite the comments three times to check it in. And in the end, I know the name of the function. I can see the inputs and outputs. The only part of those comments that were occasionally useful were purpose, details of which often changed with edits. And in reality, as long as the function isn't hundreds of lines long (another problem), I can read it and discern exactly what it's trying to do. Comments that were most useful said stuff like "this looks weird or dumb, but we had to do it this way because of this thing we and you probably didn't expect in the data/system/etc"

pc86 9y ago

For what logical purpose would a non-programmer be reading your source code and only be able to accomplish whatever their task is if you adequately comment it?