Skip to content
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

Open
leios opened this issue Jan 2, 2019 · 4 comments
Open

Code comments #570

leios opened this issue Jan 2, 2019 · 4 comments
Labels
Discussion This is open for a discussion.

Comments

@leios
Copy link
Member

leios commented Jan 2, 2019

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.

@leios leios added the Discussion This is open for a discussion. label Jan 2, 2019
@julianschacher julianschacher pinned this issue Jan 2, 2019
@InzeNL
Copy link

InzeNL commented Jan 4, 2019

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.

@leios
Copy link
Member Author

leios commented Jan 6, 2019

I agree, but the code may have language-specific things that we need to discuss too that should be commented.

@InzeNL
Copy link

InzeNL commented Jan 7, 2019

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?

@PudottaPommin
Copy link
Member

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".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Discussion This is open for a discussion.
Projects
None yet
Development

No branches or pull requests

3 participants