Programming Conventions

Description of file structures, naming conventions, and coding conventions used through the Giterary codebase.

Sure, it’s MVC… ish.

I suppose, technically, Giteary’s codebase follows an MVC-type architecture. That is, if you say that:

git is the “model”

“views” are the render and layout templating mechanism

“controllers” are a series of functions to route requests based on user parameters

That said, it’s certainly not pretty, and violates quite a few things that other codebases implement much better. I try my best to separate display logic from data logic, but honestly, PHP itself is sort of a templating language that got out of hand.

File Structure

/*.php Files for accepting parameters, routing to functions,
and providing the right bootstrapping "require"
statements to handle requests.
/css/ CSS
/js/ Javascript
/include/*.php Function definitions, named according to their site function.
/include/config.php Configuration bootstrapping
/include/util.php Utility methods used application-wide
/include/git.php Functions for interacting directly with git
/include/git_html.php Functions for translating git output to HTML
/include/display.php Functions for rendering and translating documents from Markdown, CSV,
text, or any other formats.
/include/config/*.php Configuration PHP and config "libraries"
/theme/ Storage for "theme" renderables for the templating mechanism
/theme/default/ Storage for default theme
/theme/*/renderable/ Storage for "renderable" PHP pages for the templating mechanism
/theme/*/renderable/layout Storage for "renderable" PHP pages for the templating mechanism

Function naming

git_* functions

Functions that interact directly with git. Usually the suffix will correspond directly to the git “verb” being used.

gen_* functions

Functions that “generate” HTML output, but also have the possibility to serve as “shim” functions to separate functionality like “Am I allowed to perform this function?” from the actual execution of the function.

Additionally, serves to provide a “staging area” for handling default variables or configured variables before passing off to the “executing” functions.

_gen_* functions

Functions prefixed with _gen tend to be the “executing” functions, counterparts to their parameterizing and authenticating gen functions. These tend to have more or less options than their gen counterparts, being the “advanced” interface to a particular feature, or being a function that serves more than one set of gen functional areas.

Keep Things Simple Where They Should Be Simple

If at all possible, it is recommended that you keep “logic” code out of the root *.php files, instead delegating display logic to underlying functions. For instance, the PHP file to display search.php is

Its only concern is accepting the request, search terms, and passing them to the gen_search() function. It does not call any of the git_ functions, instead relying on the gen_ HTML generation to indicate display, success, or errors.

It’s hard to strike a good distance between a piece of code doing exactly what you want and the amount of work it takes to get you there. Some problems are better left to those with doctorates in computer science or mathematics, or those that get paid handsomely to solve such problems for their employers and contribute their efforts back to the open source community.

That being said, it’s rare that I find a programming library that solves a particular set of problems in ways that:

Fit with my level of paranoia

Fit with my level of vague technological elitism

“Get out of my way” if I want to do something that might be considered unwise.

Also, package management. There are great systems out there that manage packages and their dependencies. I like to build things that are simple enough that they don’t require package management, or, can exist without the need for package management.