Day development details

Conventions

These have evolved over many years the two key ones are initial capitalisation of functions/methods and function arguments. As most other identifiers are initially lowercase it makes them stand-out.

Naming conventions

Function names	Initially Capital, camel case. eg. SomeFunction
Function arguments	Initially Capital, camel case. eg. ArgumentOne
Local variables	Initially lower-case, camel case. eg. aLocalVar
Class names	All uppercase. eg. ACTIONS
Constants	Uppercase with two parts split by underscore. eg. BOOL_ONE

So for example if you were to see foo = BAR.Buz(Fox); you'd know foo was local, Buz was a class-method (not a class variable) and that Fox had come from the surounding function call. If you saw if(bar.buz == FOO_FOX) you'd know that bar was a local instance of a class (ie an object) with buz being a value (not a method) and that FOO_FOX is a constant.

I often use a variable rv to build a return value with a final return rv; at the end.

When passing arguments to a .map() or .forEach() etc. I name the variables V,I,A as in myArray.forEach(function(V,I){number+=V*I;});

Leading underscores

You will see quite a few methods with a leading underscore such as ._FooMeInPrivate() this is a hint to programmers that this is really an internal method, and what it might perform will either be surfaced in a more practical routine, or of a rather specialist nature. For example DAYo.To32Bits() is a method you'd call on a DAYo quite normally, but DAYo._Read32Bits() is a helper method for the DAYo constructor. There's nothing stopping you using these methods, they're properly documented, but stop and have a think first.

Coding conventions

I don't bother with fancy file naming conventions. Typically I'll put each class definition in its own source file. I like to start filenames with capital letters. It's just proper and decent.
Because I use home-grown source documenters, I've evolved the following commenting standards
- Use // for real comments. /* ... */ reserved for headings etc to stand-out in an editor.
- The first contigious block of (//)comments in a file starting at the first line is transcribed into the documentation.
- Object properties, eg. in a class definition, are given one per line with the trailing //-comment being used to note it in the documentation.
- Functions/methods have their documentation immediately above the declaration. No blank lines are permitted.
- Only lines that start [optional-space]//required-space are copied to the documentation.
  // *********** FROM METHODS ************ This blank line means the preceding comments will be discarded //------------------------------------------------------------------Ignored (no space after//) // {Str} is either some sort of human input like '23 May 2014' Fancy decoration // or YYYY-MM-DD or YYYY-MM-DD HH:MM:SS // The optional {ForceFlag} can be used to use or ignore the HH:MM:SS part of the timestamp // If the HMS part is present and {ForceFlag} is DAYu.strYMDHMS then use the overloaded/encoded // time elements to create a rich DAYo //------------------------------------------------------------------Ignored (no space after//) DAYo.prototype.FromString = function(Str,ForceFlag){ // something internal Ignored (inside definition)
- In comments {...} is used to highlight arguments.
- In comments !...! is used to alert the reader
- In comments [...] is used to show an explicit string
- It's time for a rewrite of the documenter so there may be slight alterations to other highlighting codes.
This code is meant to be read and easily understood. While some Javascript oddities will be strange to coders used to other languages, clarity always comes before coding chic.

Development environment

This is a collection of javascript source files, test files, documents, distributables and tools. The documentation should be enough for a unzip of the core to be runnable, but the automation relies on node and gulp which will probably need installing etc.

What goes where

Day root
Javascript sources: DAYo.js etc. These are the core sources. DAYx.js is used for testing.
index.htm redirects to the documentation root.
bits/: Css, Images and js libraries.
PefStdDoc-min.css: My standard styles as used on the documentation
day.css: Turn Day into our logo
autoReload.js: Used to keep html pages fresh when things change behind the scenes. Documentation for autoReload.js
Dict.js: Dictionary library Documentation for dict.js
jquery.js: An old version of jQuery. This is used by the interactive testing and form-helper. Day itself doesn't use jQuery.
demo/ Home for introductory demonstration pages.
docs/ Complete documentation.
Most documentation pages are hand-crafted and use the standard styles. Style cheat-sheet
APIReference.htm is generated by the genAPI.php tool.(qv.)
Any pdf files are obsolete but may be needed for reference.
dstrn/ One day a distributable package etc. will go here.
i18n/ Internationalisation appendices
package/ results of building, minifying the sources etc.
day-dvnt.js is used for development.
day-min.js is the minified version.
tests/
testConsole.htm is the main testing console. Use this for interactive active debugging and trying out new tests.
testPlayground.htm can be used for detailed poking around edge cases and investigating the effect of configuration settings.
nonce.txt is a flag that if changed prompts the reloading of testConsole.htm. This happens at the end of the automated build process. So for example changing a script file will trigger a rebuild which in turn prompts a console reload.
scripts/ Library of (text) files definitions for tests. Tech details
methods/ Library of (javascript) files that add test capabilities. Tech details
results/ All these files are automatically generated by the node.js version of the tests. index.htm is an index. This is where you'd look at complete and regression testing results.
tools/
php/ API documentation generator
node/
gulpfile.js configures gulp.
dt.js Bulk testing program. Run with the command node dt.js
node_modules/ all the god-awful elephantine cruft installed with gulp and modules.
shell/
day.sh brings us here ready to start gulp.

Source code documentor

See Coding conventions above. This is a PHP program called genAPI.php. It's heritage goes back to 2003 but it works. An obvious wet-afternoon project is rewriting from scratch in js/node.

gulp task-runner

gulp runs in the background (using node.js) to watch for changes to sources or tests. When it spots such a change it 'compiles' everything. That's about it. Look at gulpfile.js for what the current actual and anticipated scope of automated building is. Typically you'd start gulp in its own terminal window.

$ cd /Servers/htdocs/test/2013/js/day/tools/node cd /Servers/htdocs/test/2013/js/day/tools/node $ gulp

This process doesn't normally terminate as it's always watching. Ctrl-z works to kill it in Linux. Don't ask me technical gulp or node questions as I'm very much a poke-n-hope then leave alone with getting them working.

node bulk testing

All the test scripts can be run on the server (rather than in-browser) using node. This is ideal for regression testing and only takes a couple of seconds.

$ cd /Servers/htdocs/test/2013/js/day/tools/node cd /Servers/htdocs/test/2013/js/day/tools/node $ node dt.js

You can add the name of a script file on the command line and optionally from and to lines.
The console gives a quick indication of progress, but unless you're doing console.log(...) it's just a progress log. The place to look at the results is tests/results/index.htm