3 ms·

As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should

by js8 10y ago

As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.

derefr 10y ago
Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. This is not true of comments. If we could make outdated comments produce compilation errors, we would live in a wonderful world :)
- ntsb 10y ago
  > If we could make outdated comments produce compilation errors I really hate it when the compiler ignores my comments.
- sqeaky 10y ago
  But it could. With C++ at least you can get your build to break on some comment errors. If you enable Clang's pedantic warnings, or if you setup Doxygen to emit warnings in the same format as your compiler and incorporate Doxygen execution directly into your build, you can get errors and warnings on bad comments. Doxygen supports documenting function parameters, C++ template parameters, return values then Doxygen and Clang can tell if the name listed for some of those things doesn't match the actual code or if a certain kinds of comments are missing. This won't tell you the documentation is wrong, but it would stop you from adding or removing a function parameters while ignoring documentation comments entirely. If you want to go crazy you can write Clang plugins using LibTooling and run and code you want and analyze the comments any way you choose.
- emodendroket 10y ago
  > Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. Depends what language you are working in; in some it won't fail until runtime.
- js8 10y ago
  What I was saying that choice of identifier of the variables/function does not matter for the functionality, as long as they all refer consistently to the same thing. Take code obfuscated by replacing variable names, for instance. People don't argue we should run the code through such obfuscator out of worry that the identifiers can change meaning through code changes. > If we could make outdated comments produce compilation errors, we would live in a wonderful world It is impossible. The whole point of having comments (and also identifiers) is to tie the code to things that are not formally described. If we would formally describe them, they would become the code. You could, at best, mark identifiers in comments (and what their refer to), and then you could use this to hint at comments that need to be updated (as somebody else mentioned). But it will never be a perfect process, because there will always be a boundary between formal and informal.
- eveningcoffee 10y ago
  Counter example: method findSomethingByParam1(param1) was changed to findSomethingByParam1(param1, param2). Seeing such method name in the call stack can be highly misleading.

by js8 10y ago

As others have said.. Code doesn't depend on variable/function names either. Yet you don't argue they fall out of sync, you simply update them. And this should be done for comments, too.

derefr 10y ago

Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. This is not true of comments. If we could make outdated comments produce compilation errors, we would live in a wonderful world :)

ntsb 10y ago
> If we could make outdated comments produce compilation errors I really hate it when the compiler ignores my comments.
sqeaky 10y ago
But it could. With C++ at least you can get your build to break on some comment errors. If you enable Clang's pedantic warnings, or if you setup Doxygen to emit warnings in the same format as your compiler and incorporate Doxygen execution directly into your build, you can get errors and warnings on bad comments. Doxygen supports documenting function parameters, C++ template parameters, return values then Doxygen and Clang can tell if the name listed for some of those things doesn't match the actual code or if a certain kinds of comments are missing. This won't tell you the documentation is wrong, but it would stop you from adding or removing a function parameters while ignoring documentation comments entirely. If you want to go crazy you can write Clang plugins using LibTooling and run and code you want and analyze the comments any way you choose.
emodendroket 10y ago
> Code does depend on variable/function names. When you change the name at the definition, your code fails to compile until you also change the name at each usage. Depends what language you are working in; in some it won't fail until runtime.
js8 10y ago
What I was saying that choice of identifier of the variables/function does not matter for the functionality, as long as they all refer consistently to the same thing. Take code obfuscated by replacing variable names, for instance. People don't argue we should run the code through such obfuscator out of worry that the identifiers can change meaning through code changes. > If we could make outdated comments produce compilation errors, we would live in a wonderful world It is impossible. The whole point of having comments (and also identifiers) is to tie the code to things that are not formally described. If we would formally describe them, they would become the code. You could, at best, mark identifiers in comments (and what their refer to), and then you could use this to hint at comments that need to be updated (as somebody else mentioned). But it will never be a perfect process, because there will always be a boundary between formal and informal.
eveningcoffee 10y ago
Counter example: method findSomethingByParam1(param1) was changed to findSomethingByParam1(param1, param2). Seeing such method name in the call stack can be highly misleading.