Question: I'm a javascript developer for a year now but I lack some architectural/engineering background as I was lazy in college.
In the beginning I was writing small scripts with relatively small and simple objects.

As my projects are getting bigger, I tend to use bigger and more complex objects which reflect 4-5 basic data structures which I use in various parts of my application.

I'm looking for the best way to document/keep track of the structure of these objects because when I make a new module that will use one the them, I have to make use they will respect their structure and interface so the previous/next modules using them won't break.

What I was doing until now was to document an object like this:

```
/** description of the object/data structure
var myObject = {
    property1: "", //explain here what is this property and what type it is (number,string etc)
    property2:blabla,
    etc...
}
*/

```

This ended up to huge parts of comments which are ugly in the code and distructing too.

Could you suggest some ways of either visualize my objects/data structures or document them so I can fast recall how they should look like?

Answer: 
There are several tools for that out there, but here's a few:

* [njsdoc](https://bitbucket.org/nexj/njsdoc) - *"NJSDoc is a Documentation tool for JavaScript that
works by **executing code**."*
* [JSDuck](https://github.com/senchalabs/jsduck)
* [jsdoc](https://github.com/jsdoc3/jsdoc)
* [YUIDoc](http://yui.github.io/yuidoc/)
* [Natural Docs](http://www.naturaldocs.org/)
* [DocumentJS](http://javascriptmvc.com/docs.html#!DocumentJS)
I think you might be interested in the information provided here: 
<http://javarevisited.blogspot.gr/2011/08/code-comments-java-best-practices.html>

It's about java but they can also be applied in Javascript (some of them)

Summarizing the key points:

1. Focus on readability of code
2. Don't write what code is doing
3. Always write why you are writing this piece of code
4. Always try to finish your comment in as few words as possible
5. Always put comment while commiting code in source control repository
6. Give your code to fellow developer to understand

Regarding your code, I have to say that from personal experience I find that writing comments on the previous line rather than next to the code, is more clear and easy to read.
E.g.

```
var myObject = {
    //explain here what is this property and what type it is (number,string etc)
    property1: "", 
    property2:blabla,
    etc...
}

```