2. Coding Style

While some configurations are less picky about this, I find I end up scratching my head at my own code months later if not adhering to a coding style of my own crafting. This page details the elements of that style and then shows an example file from the configuration as means of illistrating what the coding style amounts to.

---

## 'Comments, My Dear Watson, We Must Have Comments!'

File Header Comments

Each file has an ASCII art version of its long form name, which is decided somewhat hapzardly, followed by a comment bar and an explanatory text about the file, if that is even necessary. The ASCII font used is always the Chunky font, which is the only one I find tolerable and readable personally. This looks like so:

--  _____
-- |     |_.-----.-----.-----.
-- |       |  _  |     |  _  |
-- |_______|_____|__|__|___  |
--                     |_____|
--  _______
-- |    ___|.-----.----.--------.
-- |    ___||  _  |   _|        |
-- |___|    |_____|__| |__|__|__|

--  _______ __ __   __
-- |_     _|__|  |_|  |.-----.
--   |   | |  |   _|  ||  -__|
--   |___| |__|____|__||_____|
-- ------------------------------------------------- --
-- this comment explains the file if that is necessary
-- and is not always present

Main Sections

Each file in these configurations fits a standard pattern, which is true of most modularized AwesomeWM configurations. These sections will be beneath a comment bar and have their names embedded in their own comment bar like so:

-- ------------------------------------------------- --
-- -------------------- section -------------------- --

and these common sections, in their respective orders, are:

1. variable declaration
2. methods
3. signals
4. return statement

unless there is need to call external libraries or other modules in that particular file (happens sometimes even with global_variables) in which case it will be

1. external library definitions
2. variable declaration
3. methods
4. signals
5. return statement

NOTE: The comments in this code are not being used to generate documentation like the upstream project, which is due to divergent audience, use case and time constraints not a comment on the utility of such an application.

Comment Bars

Each section of code is divided from the rest by a single 55 character long bar of lua's comment indicator, with the first and last two separated from the rest by one space. Which looks like:

-- ------------------------------------------------- --

Explanatory Text

Below the comment bar, unless too redundant to write is a comment describing the functionality of the snippet below it.

Sometimes Not So Much

Sometimes the explanatory comment will not come after a comment bar, generally because it only applies to the line directly below itself, which doesn't naturally section from the rest of the code.

---

What's Not In the Code

If you have any experience with awesomewm or lua and open a random file, you may wonder why no section at the top exists to call libraies and other files outside of the subdirectory init.lua pages, this is because this configuration is using a file that handles all the global variables in one place and is called early such as to provide these as globals to all subsequently called files and saves me a lot of time and heart ache when things decide they don't want to work that day, but comes at a price in terms of making it more laborious to remove files from this configuration and then determine what needs to be require()'ed and where. Sorry about that, but otherwise should be easy to chop bits out and use them in your own configuration.

This repository is also not literate or semi-literate programming as that is a bit much given how incredibly huge this repository has become (and stayed through several incarnations), I don't like org-mode despite several attempts to convince myself I do (yes I could also use markdown, or better yet HTML but still, a little too much all around) & don't want to endure the debugging of the process I would need to set up to yank the code out of the super-blabber I would probably turn that into. Sorry, maybe if a less onerous tool to configure than emacs with its awful lisp configuration process that has plenty of evil by default or the Neovim extensions for org-mode existed I would but for now not gonna happen. Instead I wrote these docs out for you!

---

## Formatting, Linting & Code Maintenance

To format the code, the best formatter to not mangle the various key configuration files I have settled on is the vscode-lua-format available as a vscode extension (which requires I reopen the files in vscode before commits, which is at times, unpleasant in the extreme). At least until I have a reliable means of tweaking the options available in neovim to do roughly the same thing, or look up the extension then use its source to build my own neovim friendly formatter.

To lint the code, I recommend luacheck which can be installed either from your package manager or using luarocks, then a bit of additional tooling and it will work with your IDE (either a vscode extension or setting up an autocommand on neovim should work fine). I would advise, due to the unique nature of the AwesomeWM API compared to other projects using Lua, that you maintain a .luacheckrc file at the directory root to house any and all of the project-wide linting exceptions in case you care to eliminate them all, which you should as it makes later debugging much easier.

---

What Is Its Own File and What Is Kept In the Same File?

I wish I knew, as this is somewhat code anarchy here and elsewhere in the AwesomeWM world, but my general rule is to keep in one file what makes sense to roll together in a single return statement if one is even necessary (signals waiting for events obviously won't need these among many other exceptions to this). If that fails to limit a file's scope, I do prefer to keep files shorter and require little to no scrolling but that too is hardly always the case and sometimes awesome's peculiarities alone prevent this sort of order from being attainable.

If you think something would make more sense together or separated, submit a pull request and I am happy to take it into consideration if not adopt your changes if they make sense.