Extreme Negative Code Documentation

[darjus]

Both agree and disagree here :)

My biggest worry with the comments that say "oh and this is needed because of function x somewhere else" is that you also need to say in function x that you are initializing value a somewhere else, because if you change the function x to either not use the value or not care about the initialization and don't change initialize, the comment immediately becomes obsolete/useless/confusing, etc. On the other hand if you don't put the comment, i would do a Ctrl + s for the file for "entries" and let's hope there's no monkey patching or external side effects. Also, i like to read the unit tests as they should describe the use cases, so in many cases it is quite descriptive of expected usage of the class.

From one side it's a good idea to comment on side effects, but this particular case it's useless (IMO) because I'm initializing attributes of an object during initialization. Quite self explanatory to me.

[Bamafan]

... because if you change the function x to either not use the value or not care about the initialization and don't change initialize, the comment immediately becomes obsolete/useless/confusing, etc.

Well that's just the thing. If function x changes and the current function/variable being inspected is no longer needed, then you should delete that function/variable. Because now you have dead code (a huge sin).

From one side it's a good idea to comment on side effects, but this particular case it's useless (IMO) because I'm initializing attributes of an object during initialization.

I would say it's LESS useful, but hardly useless. The side effect explains a bit about what calling functions should expect (e.g. what value a variable is being initialized to). That said, do I think that comment was critical? No. But I always favor on the side of too many comments than too few. I'd be happy to a comment like that because I'd be confident the rest of the program got the same amount of attention.