I was asked to provide an overview of a project that I was working on and I ended up providing a style guide in the overview documents and thought it was worth sharing. It’s in no way all encompassing, but it provides a good core for self documenting code, in my opinion.
Simple Styleguide
Naming Conventions
- Files
- Always lowercase
- Words seperated by an underscore
- Controllers
- Named after the functional area they are meant to add
- Models
- Named after the table they access in the database
- Tagged with a _model to denote the file as a model
- Views
- Named after the controller which requires that views
- At most 1 primary view per controller
- You can provide a sectioned views using the sections folder
- Sections should be stored in a folder named after the primary view
- e.g. /views/sections/{primary view name}/logged_in.*
- Tagged with a _view to denote the file as a view
- Classes are capitalized version of file name
- Function/Method
- Words seperated by an underscore
- Generally use a verb at the beginning to describe functionality
- Variables
- Normally named after the field they access
- Create model objects as m_{model name}
Spacing
- Indenting
- Uses spaces instead of tabs, 2 or 4 spaces
- Classes
- Brackets start on next line at the same level as the class
- Brackets end on the same level as the class
- Functions
- Brackets start on the next line at the same level as the function
- Brackets end on the same level as the class
- Add a new line to split functions up for readability purposes
- Control Blocks
- Brackets start on same line as the beginning of the block
- Provide one space between the end of the logic and the bracket
- Brackets end on the same level the control block
Extra Bits
- Functions that have a similar focus should be close to each other