-
-
Notifications
You must be signed in to change notification settings - Fork 356
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Code comments #570
Comments
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". |
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.
The text was updated successfully, but these errors were encountered: