|
|
# Style Guide
|
|
|
|
|
|
This tries to be a comprehensive stlye guide. If you find something missing, odd or unconvenient, for the love of god please, arrange a discussion with all currently active developers to *agree upon a common rule* and add to/update these guide lines. Conflicting styles do nothing but harm and hamper reading.
|
|
|
|
|
|
## Commenting
|
|
|
|
|
|
Just in case nobody told you before: *COMMENT YOUR WORK*. This makes it easier for people (even future you) to understand, what is happening.
|
|
|
|
|
|
Adopt commenting style of *TableModel.* files.
|
|
|
|
|
|
Regular comments are associated with the person who is mentioned under "fille with life by:" in the header file. For all others you need to "register" in the change log and start your comment with your initials. With the use of the change-log and initials your work is duely credited. Version control does not make this obosolte, especially since files might be handed on stand-alone basis somewhere somewhen.
|
|
|
|
|
|
So in short: John Doe writes his name and changes to the change-log and comments his code using //jd - <actual comment>.
|
|
|
|
|
|
## Naming
|
|
|
|
|
|
| Set/Type | Rule | Reason(ing) |
|
|
|
| ------------- |-------------|-----------|
|
|
|
| General | Use a new upper case instead of _ to seperate words | saves space |
|
|
|
| General | Think about word order | stepTime means something other than timeStep |
|
|
|
| General | Column width in source files is 100 and in header files 60 | some limit is sensible and 80 is too few characters to work with equations and descriptive names (see below) |
|
|
|
| General | Use, what already exists, if possible | avoid reinventing the wheel |
|
|
|
| General | Use std-library in algorithm <br> Use Qt-library in GUI | Makes the actual model usable by e.g. terminal applications without the need to install Qt, but leaves people wanting to use the GUI OS-independent |
|
|
|
| General | Make use of spacebar *A LOT* and use newline often, too | easier to read |
|
|
|
| Classes | Start with an upper case | easier to distinguish |
|
|
|
| Classes | When in GUI: add the type at the end if sensible | e.g. Preferences is a regular class and PreferencesDialog is used to display these as an independent window. The logical link as well as the behaviour of the dialog are implied that way. |
|
|
|
| Classes | Create operator= | provision of exptected behaviour |
|
|
|
| Classes | Create copy constructor | provision of exptected behaviour |
|
|
|
| Classes | Avoid creating (sub)classes | The model is designed to model only essential behaviour in a generic way. Create a class only if essential *behaviour* differs in a notable way from existing classes. If only essential behaviour is missing, but fits an entire class, implement that within that class.|
|
|
|
| Classes | Members should be private or at least protected | keeps changes to an observable amount of code |
|
|
|
| Classes | If members neeed to be accessible use get/set functions | see above |
|
|
|
| Functions | Start with lower case | easier to distinguish |
|
|
|
| Functions | Start with a verb | makes it apparent, that something is about to be done |
|
|
|
| Functions | Assign const anywhere possible/wanted | enforces a gateway and some thought |
|
|
|
| Variables | Member variables start with an m_ | easier to distinguish. "m_" means member |
|
|
|
| Variables | Use *descriptive* names | avoids confusion of what the hell \alpha means *this* time |
|
|
|
| Spacebar | Use it when declarin pointers/references | makes it easier to distinguish from dereferencing |
|
|
|
| Spacebar | Use it around operators | x = a + b is easier to read than x=a+b |
|
|
|
| Spacebar | Use it after "if", "for", "while", etc. | easier to read |
|
|
|
| Spacebar | Use it after commata | easier to read |
|
|
|
| Spacebar | Use it to align comments (probably faster with tab-key | faster to read comments |
|
|
|
|