Code comments

[sindresorhus]

Since TodoMVC is for learning, we should make sure all our implementations, both new and existing ones are fully commented.

Going to update the app spec, just need to make sure we ask for the right kind of comments. I've seen a lot of different commenting styles and only liked some. IMO commenting should explain the why (and sometimes the how), code should explain the how and what.

Anyone have a good resource we can link to about proper code commenting?

[sindresorhus]

@passy @addyosmani

[passy]

I saw this article yesterday: Yes, your code does need comments. I think it's a good guideline, but would go even one step further since this is not a regular application, but is intended for learning. So too much commenting is pretty hard to achieve.

[addyosmani]

Do we want to go down the path of docco compatible comments or something similar so folks have more literate code or is it enough to ask that they just comment more thoroughly?

Let's find the app in our collection that is exemplary comments wise. Think the Ember guys were going to try doing this for theirs.

[ColinEberhardt]

I've just been using ToDoMVC in order to familiarise myself with Dojo. In terms of code-level comments, this implementation is rather good. However, what I personally find very useful, in fact more useful, is something which explains the overall structure of the application.

As an example, looking at the Dojo code:

https://github.com/tastejs/todomvc/tree/gh-pages/architecture-examples/dojo/js/todo

What's the purpose of the code within the form folder? What are the common responsibilities of those files? As somemone evaluating Dojo, should I be concerned with this code?

Where is the code that implements the persistence requirement? Has the author had to create their own UI widgets in order to meet the spec?

I like to be able to quickly 'home in' on the interesting bits of code. The code that implements the actual to-do list logic! Code comments help you understand the purpose of each function, and perhaps the responsibilities of a specific file. However, I find myself having to navigate through, and read, a number of files before I can build up a picture of the overall application structure.

I would like to see something that describes the folder structure and the responsibilities of the various files for each framework implementation.

[hura]

I think todomvc should take inspiration from this type of source commenting:

http://tutorialzine.com/2013/08/learn-angularjs-5-examples/

+1 for more comments.