Comment by godelski
2 years ago
> For example, having the parameter to a function declared `const` means the function cannot alter it, and this is checked by the compiler. It won't be necessary to mention that in the function documentation.
Actually you should mention it in the documentation. There's 2 types of documentation, so it's easier to just do the one: documentation for users, documentation for developers. Unless you work absolutely alone on all your projects and you don't open source them, someone else is going to be reading your code.
Why should the documentation repeat that a pointer to const cannot modify what it is pointing to?
> Why should the documentation
>> someone else is going to be reading your code.
Someone else is going to {read,edit,write,maintain} your code. Which means __anything__ the code does should be explained. Before you were suggesting documentation is only for the user. Documentation is also important for the developer. Whoever takes over your code later or works on it with you.
I was objecting to comments like these:
No value is added by such comments. Hence, the more expressive a language is, the fewer comments are needed.
Of course, a precondition is that the person reading the code knows the language reasonably well, and I'm not writing a language tutorial.
1 reply →