algorithm-archivists
Code comments
We have been doing a poor job of commenting code in the AAA. I understand that some code is self-explanatory, but because many people may be learning new languages along with implementations, we should probably be more heavily commenting code.
I would like to discuss the best way to comment the code for different languages and ways in which we might share these comments across different languages.
What happens in the code is (or, should be), described in the book itself. When writing code comments, I'd say it's good practice to reference to these certain parts of the book.
Whichever way we choose to comment code: If a comment describes something completely new, the code should be rewritten to match the book, or the book should be rewritten to match the code.
I agree, but the code may have language-specific things that we need to discuss too that should be commented.
I can see that, in that case we should define what we see as a "language-specific thing." Would we set up a list of "universal things," where everything that doesn't match this list should be commented?
Well this all depends on answer for question What level of language knowledge are we targeting in implementations?, because on this depends what is/are language specific thing(s). It's not reliable to comment everything, because how InzeNL wrote, the main guide is text of the chapter.
Code comments could be worthy in neat tricks, where code was simplified using something, what may not be general knowledge. Or commenting some parts in meaning of "go to check some part of text".
