On 2010-06-10, at 9:07 PM, Maxime Chevalier-Boisvert wrote:
Erick setup a repository with a script to setup JsDoc and other tools (js_tools.git).
After toying some more with small bits of JavaScript and JsDoc, I will have to agree with Marc and Bruno regarding the module prefixes. It seems that JsDoc doesn't document modules very well even when they are objects. We should possibly consider trying to improve the tool ourself. If we could have a per-file summary, it would already be better.
I have also discovered that there are problems due to the initialization order. Functions in all JavaScript files are globally defined before anything else, but only if they are defined using the function somename() syntax, not if we assign them to a variable. Hence, defining functions globally saves us the trouble of having to figure out in what order we have to define functions.
Fine.
However, I would propose, as a compromise, that we still name the functions themselves using hungarian notation, eg:
As a compromise to what? Is this a technical compromise or a political one? I'm all for technical compromises which can be argued on their objective merits, but political compromises make me feel uneasy. Coding style has some aspects which can be evaluated objectively, but for the most part it is a question of taste and thus depends on the people in contact with it (i.e. the programmers).
I'm not a big fan of CamelCase. I find it hard to read and the rules can lead to inconsistencies (should is_ASCII_EOF be mapped to isAsciiEOF or isAsciiEof or isASCIIEOF?). When writing the parser I started using CamelCase, but I abandoned it when I realized that I could not use it consistently because some functions are generated automatically from the grammar definitions and also because part of the code is a translation from Scheme code (where it was natural to use underscores instead of dashes). I do however like the rule of capitalizing functions which are constructors (which is what C++ does).
So I'm not quite sure what to do with this issue. We can bring it up for a vote among us after some more discussion. For the time being each one should just use the notation that they are most comfortable with. We'll refactor if need be. At this point what is important is that we advance the implementation... i.e. code!
Marc