organization
#define organization: \
I------------------------------------------------------------------\
I------------------------------------------------------------------\
I _____ _ _ _ \
I | _ | (_) | | (_) \
I | | | |_ __ __ _ __ _ _ __ _ ______ _| |_ _ ___ _ __ \
I | | | | '__/ _` |/ _` | '_ \| |_ / _` | __| |/ _ \| '_ \ \
I \ \_/ / | | (_| | (_| | | | | |/ / (_| | |_| | (_) | | | | \
I \___/|_| \__, |\__,_|_| |_|_/___\__,_|\__|_|\___/|_| |_| \
I __/ | \
I |___/ \
I------------------------------------------------------------------\
I------------------------------------------------------------------I
" \
Every line of code is written without reason, \
maintained out of weakness, \
and deleted by chance. \
" - Jean-Paul Sartre's Programming in ANSI C
• this chapter contains information on how to optimize readability
and reusability in the context of programming
• nothing here is hard science or carved into stone
Clean_code:
• code that is readable, maintainable and reusable
— an expression to describe "pretty code":
• well named symbols
• logical organization
• meaningful abstractions
• as concise as possible
• its important when future extension is planned or
when the project is open source (security reasons);
there are however situations where it is in fact not
important, such as game development for money;
(games are known to be extremely dirty in particular)
• associated with a cargocult of nudevs and academics,
who got caught up in a purity-spiral resulting in horrific mutilation of the initial goals
• The Boy Scout Rule - "Leave the campground cleaner than you found it."
Design_smells:
• a sign of code not being clean
Rigidity : hard to change or extend
Fragility : footguns which cause problems in illogical places
Immobility : lack of reusability
Viscosity : filled with footguns
Complexity : useless abstraction or infrastructure
Repetition : an abstraction is missing
Opacity : hard to read and understand; does not express its intent well
Types_of_dirty_code:
• spaghetti code is whats hard to read and maintain code is called;
its creation is due to negligence and lack of skill
• ravioli code is whats incredibly fractured code is called;
very small functions and senseless class creation for
setting up a non-practical hierarchy are common symptoms
• lasagna code is what code with intertwined layers is called
• hairball code is a chunk of big, monolithic code that could go berserk anytime
• code smell is a symptom or indicator of bad code; exclusively used by insufferable pricks
• the most important rules of thumb to dodge spaghetti code are forward planning and self consistency
Uncle_Bob: Uncle_Bob:
• (((Robert C. Martin)))
• author
• public speaker
• this individual is highly deceptive and dangerous,
keep away if possible
books:
• your time wasting ink diarrhea that isnt worth the paper its written on
Clean_code:
• his most popular book
• the only good ideas it contain are rephrasings of well known
(at the time that is, now we live in the dark ages)
ideas of other actually great minds
• to read something along the lines of what the title promises you,
consult "Ada 95 Quality and Style:\
Guidelines for Professional Programmersthe Ada"
The_clean_coder:
• "professionalism is important"
• "committed bug to telephone company; hard to find; major fuck up"
• "catch bugs before they get to quality control"
• reads like the self-help book of a cult
• 4th pillar of extreme programming (attention): The Book
• teaches absolutely nothing, simply asks you to "stop being bad",
without teaching how to improve or be better organized
• worthless scam
Clean_Architecture:
• for fairness sake, i will here by note that from 28 and onwards,
the book becomes readable and interesting
• "Now let’s look at the company’s productivity over the same time period,\
as measured by simple lines of code (Figure 1.2).";
(the graph shows a drop, even tho number of engineers increased);
LoC is NOT a measure of productivity;
in fact, in a clean code base,
each line of code should become increasingly more expressive,
as they can harness the effort already invested in the project;
while i dont doubt that there has been a drop in productivity in practice,
the way he presents it is dumb and or deceptive;
the hiring methodology of the company is never questioned
• "Jason Gorman experiment"
i am a schizophrenic man who likes anecdotes, yet this is fishy even to me;
one man, studied himself, with and without something intangible;
salesman psyop
• "If you give me a program that works perfectly but is impossible to change,\
then it won’t work when the requirements change, and I won’t be able to\
make it work. Therefore the program will become useless."
"If you give me a program that does not work but is easy to change, then I\
can make it work, and keep it working as requirements change. Therefore\
the program will remain continually useful."
here you go buddy, have fun:
signed main(void) { return 0; }
• *rambles about irrelevant things to reach feature length*
(to be fair, its significantly higher effort than his other works)
• "My favorite example is the Employee class from a payroll application. [...]"
he is perfectly correct, what he fails to realize however,
is that the initial mess was produced by the way of thinking radical OOP
languages inevitably result in;
the obsession with encapsulation results in an explosion of the code base
even for such simple examples;
programers however like to be lazy, they WILL add methods without consideration
until the codebase catches on fire, because in their heads its preferable
to the alternative, which is a direct consequence of the struct their
language forces on them
• "This is obviously true for source code dependencies that can\
force unnecessary recompilation and redeployment—but it is also true\
at a much higher, architectural level."
i find it laughable that he was unable find an example for the later,
but promptly gives one the former, in a book,
allegedly centered around architecture
• "We are now living in the age of software reuse\
—a fulfillment of one of the oldest promises of the object-\
oriented model."
in what world does this heretic lives in?
the only code being reused is C or C wrapped with a bow tie (e.g. python),
that and whatever the fuck javascript is doing;
OOP has been a detriment to software reuse
• "But there are different kinds of duplication. There is true duplication, in\
which every change to one instance necessitates the same change to every\
duplicate of that instance. Then there is false or accidental duplication. If\
two apparently duplicated sections of code evolve along different paths—if\
they change at different rates, and for different reasons—then they are not\
true duplicates. Return to them in a few years, and you’ll find that they are\
very different from each other."
actually good point
• he makes some good points about coupling in the context of micro-services
• he seems obsessed with the evil of recompiling and redeploying
• while i can see where he is coming from in his database argument,
time and sqlite has proved him wrong
Agile_Software_Development_Principles_Patterns_and_Practices:
• wash your PPP
• goes over an esoteric list of principles that help very little in practice
Formatting: Formatting:
Auto_formatters:
• a program that formats code for you
• they tend to be horribly specific to both style and language;
which is understandable, the problem is that theres not an abundance of them
clang-format
prettier
pgindent
• the most problematic arguments over formatting arise from many,
especially C style languages being whitespace agnostic
• people used to one style of formatting have trouble reading
other styles; while this divide is not too large and can be bridged
in a reasonable amount of time, shit tends to hit the fan first
• some methods of utilizing whitespaces is objectively more readable than others
• indentatin is the act of separating codeblocks with different amounts of leading whitespace
Width:
• reading/editing code offscreen to the side is very painful
• at the age of CRTs, about 80 chars could fit comfortably on the screen
• nu-gurus suggest the current average should decide the maximum width { 150 in 2009 }
• 80 is still preferable, because its clearly enough, does not make assumptions about
the readers set up and allows for split, side by side views
— there are a number of well established and defined formatting styles
• in this context "while" marks a generic block head { for, if, etc.}
○ Allman
while
{
[...]
[...]
}
○ K&R
while {
[...]
[...]
}
○ GNU
while
{
[...]
[...]
}
— from "GNU Coding Standards":
"\
It is important to put the open-brace that starts the body of a C \
function in column one, so that they will start a defun. Several tools \
look for open-braces in column one to find the beginnings of C \
functions. These tools will not work on code not formatted that way. \
\
Avoid putting open-brace, open-parenthesis or open-bracket in column \
one when they are inside a function, so that they won't start a defun. \
The open-brace that starts a 'struct' body can go in column one if you \
find it useful to treat that definition as a defun. \
\
It is also important for function definitions to start the name of \
the function in column one. This helps people to search for function \
definitions, and may also help certain tools recognize them. \
"
• 40 years later, this is yet to be readjusted, with more modern tools in mind
• i have this theory that they simply wanted to make C
look as much like Lisp as possible
— from "Linux kernel coding style":
"\
First off, I'd suggest printing out a copy of the GNU coding \
standards, and NOT read it. Burn them, it's a great symbolic gesture. \
"
• based.
○ Whitesmiths
while
{
[...]
[...]
}
○ Horstmann
while
{ [...]
[...]
}
○ Haskell
while
{ [...]
; [...]
;
}
○ Pico
while
{ [...]
[...] }
○ Ratliff
while {
[...]
[...]
}
○ Lisp
while
{ [...]
[...] }
Naming: Naming:
• names are important, in fact, developers tend to get autistic regarding them
• the longer the variables life time and greater the scope,
the more descriptive the name should get { global hexagon_grid_sprite; for i in myList }
• try not to use names that are confusable with conventions
• make bool vars a question, prefer "is" over "are" { is_banned }
• prefer humanly pronounceable names
• use one word per abstraction
• please stop using .length() and .count(); .size() is much easier to type,
but regardless, PLEASE PLEASE AT LEAST STOP MIXING THEM BY CONTAINER
Cases: Cases:
kebab-case:
• if [...] is going to have multiple words in its name, separate the words with '-'s
• many languages doesnt support it
• even when its supported, the '-' might get interpreted as a minus sign leading to an unwanted subtraction and a hard to find bug
{ this-is-a-kebab-case-example }
— when all letters are capitalized also, its called "screaming kebab case"
{ THIS-IS-A-SCREAMING-KEBAB-CASE-EXAMPLE }
snake_case:
• if [...] is going to have multiple words in its name, separate the words with '_'s
{ this_is_a_snake_case_example }
— when all letters are capitalized also, its called "screaming snake case"
{ THIS_IS_A_SCREAMING_SNAKE_CASE_EXAMPLE }
camelCase:
• if [...] is going to have multiple words in its name, make every word start with a capital except the first one
{ thisIsACamelCaseExample }
PascalCase:
• if [...] is going to have multiple words in its name, make every word start with a capital
{ ThisIsAPascalCaseExample }
Ugly_Case:
• make every word start with a capital
• if [...] is going to have multiple words in its name, separate the words with '_'s
{ This_Is_Ugly_Case_Example }
Getter_setter: Getter_setter:
Common:
function get<member>()
function set<member>()
• with mixing all Cases known to man
Qt:
function <member>()
function set<member>()
• functions named directly after members are considered getters
• the "get" is omitted as redundancy
Hungarian_notation: Hungarian_notation:
• "Hungarian naming"
• standard for {variable} naming
• applies mainly to static-ally typed languages and especially to C-like languages
— the main counter argument against it:
"The compiler/interpreter already knows the type,\
specifying it without guarantees is redundant and meaningless."
the counter is:
"While the compiler/interpreter may know the type, i do not necessarily.\
The name also specifies what the type is meant to be,\
therefor a miss-match signals a bug."
the counter-counter is:
"pronounYou verbShould adverbNever verbUse adjectiveHungarian nounNotation,\
prepositionIt verbMakes collectivenounEverything adverbSo\
comparativeBloody adjectiveHard infinitiveTo verbRead."
• widely considered bad practice; taken to its extreme, i do agree,
but applying it with care (MACRO_NAMING, global type prefixing) can be neat
• historically attributed to a microsoft employee who happened to be Hungarian,
however a less organized version of the notation has existed since
the beginning of compsci
Variables:
[prefix]([qualifier])[identifier] : Hungarian notation variable name
○ [prefix]
• a bunch of type-s pasted together
• pasting is done in the order as they apply
○ [type]
+-----------+------------------------------------------------------------+---------------------+
| type | Meaning | Example |
+-----------+------------------------------------------------------------+---------------------+
| p | Pointer | Finger* pfinRude |
| s || str | String | String sName |
| sz || psz | Null terminated string | char* szName |
| h | Handle | HWND hWindow |
| c | Char | char cLetter |
| y | Byte or Unsigned Char | byte byMouthFull |
| n | Integer | int nSizeOfArray |
| f | Float | float fRootBeer |
| d | Double | double dDecker |
| b | Bool | boolean bIsTrue |
| u | Unsigned... | |
| w | Word or Unsigned Integer | unsigned int wValue |
| l | Long | long lIdentifier |
| dw | Double Word or Unsigned Long Integer | |
| C | class | Class CObject |
| I | Interface (class with only virtual methods and no members) | |
| X | Nested class | |
| x | Instantiation of a nested class | |
| m_ | Class Member Identifiers | |
| g_ | Global | String* g_psBuffer |
| v | Void (no type) | |
+-----------+------------------------------------------------------------+---------------------+
Nonstandard_types:
• type shall always be lower case
• shall not conflict with other types
• the first few letters of types full name is recommended
○ [qualifier]
• describes the job of the variable
+-----------+----------------------------------------------------------------------+
| Qualifier | Explanation |
+-----------+----------------------------------------------------------------------+
| Sav | A temporary from which the value will be restored |
| Prev | A value that follows one behind a current value |
| | in an iteration (eg. linked list node pointer) |
| Cur | Current value in some iteration |
| Next | Next value in some iteration |
| Nil | A special illegal value that is distinguished from all legal values. |
| | Typically denotes a certain absence of a legal value. |
| Min | Smallest legal index in an array or list. Typically zero. |
| Max | A strict upper limit for legal indexes in an array or list. |
+-----------+----------------------------------------------------------------------+
○ [identifier]
• what the variable would normally be called
• adjectives succeeds the word it describes
• Pascal case
Functions:
• camel or Pascal case
Macros:
• SCREAMING_SNAKE case
Structuring: Structuring:
• a one-size-fits-all technique for struct-ing is a pipe dream
• both too many things in a single folder and too many folders
will become a hellscape to maneuver
Flat_structure: Flat_structure:
• when all files of a project are contained in the same root directory
• only use with projects consisting of only a few files
Modularized_structure: Modularized_structure:
• there are directories located in the root,
which contain source files ordered by theme/purpose
• used when projects are too large to use flat structure,
but still very small
• by having every resource to work on a single, specific page,
access becomes trivial, with no overhead
• best optimized for per-feature splitting of work
{ rest-api/
├── main.go
├── user/
│ ├── user.go
│ ├── login.go
│ └── registration.go
├── articles/
│ └── articles.go
└── utils/
└── common_utils.go
}
— commonly used for medium sized webdev projects; when there are not many pages,
however each is complex and share relatively few resources
• module-s most often that correspond to the page they make up
{
Poker/
├── Prephase/
│ ├── prephase.php
│ ├── prephase.css
│ ├── startgame.js
│ └── addUser.js
├── Login/
│ ├── login.php
│ ├── signin.php
│ ├── logn.css
│ └── validate.js
├── Game/
│ ├── game.php
│ ├── game.css
│ ├── call.js
│ ├── fold.js
│ ├── raise.js
│ └── check.js
├── global.css
└── global.js
}
Kenneth_Reitz_structure: Kenneth_Reitz_structure:
• as it was created for python it best applies for languages
where all source files are equals {python, bash; NOT C++, HTML}
— Directory:
• "Repetitive paths are confusing for both your tools and your developers.\
Unnecessary nesting doesn't help anybody (unless they’re nostalgic for monolithic SVN repos)."
[Name]/
├── docs/ : directory containing all references and documentations
├── tests/ : directory hosting debug tests and dummy examples;
│ preferably make tests files independent of SETUP (ie, use relative paths)
├── MAIN(/) : directory for all of your code, or if it fits in a single file, that, located directly in [Name]
├── Makefile : GNU make file for automating generic tasks
├── LICENSE : plain text document that shall contain the fill license text and copyright claims
├── SETUP : executable or plain text instructions to ease setting up your project on any machine
└── REQUIREMENTS : plain text list of requirements, preferably language standard compatible {python => pip}
Chad_Project_structure:
• adopted by a small group of terminally online schitzophrenics
• highly recommended
[Name]/
├── documentation/ : all documentation and relevant external resources
│ ├── TODO.md : description of mayor tasks to be done and relevant road-blocks
│ ├── developer_quide.md : information for contributors
│ ├── [Name].md : manual page for the application/library
│ └── reference.md : dry dump of facts (if relevant)
├── test/ : all system and unit tests
├── source/ : all internal source code
├── library/ : all external source code
├── object/ : all temporary files (intermitten compile steps)
├── tool/ : helper scripts and such {gdb config}
├── Makefile : GNU make file for automating generic tasks
├── LICENSE.md : license
└── README.md : project description
OGS:
• the only known reference to it is inside the legacy source code of cscope
• may or may not be related to the Quike II engine
• folders ending with .ss are considered subsystems
• folders inside subsystems are considered books
{
source/
├── main.c
└── networking.ss/
├── irc.c
└── ssl/
└── ssl.c
}
Core_java: Core_java:
[Name]/
├── docs : documentation
├── bin : the compiler and other tools
├── demo : demonstrations
├── include : include files
├── lib : library files
├── src : source files
└── jre : Java runtime environment files
Canonical_Project_Structure: Canonical_Project_Structure:
• "The canonical structure is primarily meant for a package – a single library or program\
(or, sometimes, a collection of related programs) with a specific and well-defined function. "
• if a project consists of a library and an executable, then they should be split into separate projects
— Directory:
[Name]/
├── [Name]/ : contains all source files, not further separated into subfolders
└── tests/ : contains all debug tests and dummy examples, optionally further separated into subfolders
{
libhello/
├── libhello/
│ ├── hello.hpp
│ ├── hello.cpp
│ └── hello.test.cpp
└── tests/
└── basics/
└── driver.cpp
}
By_file_type: By_file_type:
• source only
• used for small, but not trivially small webdev projects
— file types are sorted into subdirectories based on purpose (not strict mime)
{ [...]/
├── js/
│ ├── myAnimation.js
│ └── validate.js
├── css/
│ └── global.css
├── img/
│ ├── background.png
│ └── cat.gif
└── pages/
├── home.html
└── article.php
}
— if there is a clear core file type in the spotlight, then it should not be nested, rather silently placed next to the folders
{
[...]/
├── js/
│ ├── myAnimation.js
│ └── validate.js
├── css/
│ └── global.css
├── img/
│ ├── background.png
│ └── cat.gif
├── home.html
└── article.php
}
• this avoids all kinds of overhead {typing}
• if you feel the need to subdivide folders {js/homepage/}: stop; navigation will soon become very painful
Feature_Sliced_Design: Feature_Sliced_Design:
https://feature-sliced.design
• or FSD
• used for large front-end projects
— the top components of an FSD project are called layers
• there are 7 layers, named the same across all projects
+--------------+
| 1. shared |
+--------------+
| 2. entities |
+--------------+
| 3. features |
+--------------+
| 4. widgets |
+--------------+
| 5. pages |
+--------------+
| 6. processes |
+--------------+
| 7. app |
+--------------+
• look it up, its a good example of insanity / complexity hell
?!: " \
Aside: Make a util directory and keep different utilities in different files. \
A single util file will always grow until it is too big and yet too hard to split apart. \
Using a single util file is unhygienic. \
" - YYY:
https://programmingisterrible.com/post/139222674273/write-code-that-is-easy-to-delete-not-easy-to
Code_discovery: Code_discovery:
• the process of getting to know undocumented code
Indexing:
ctags [option]+ <file>+ : classical source indexing program
• creates CSV like "tags" files
• fast
• supports many languages
• only indexes declarations
cscope <options>+ <files>+ : classical C/C++ indexer and browser
csope <options>+ <files>+ : maintained fork of cscope
• improved TUI
• improved code quality
• rolled by (Me)
scourcetrail : visual source code browser
• node based (not as in js)
• slow as fuck
• due to the way nodes are displayed, not too useful in production
Code_query_languages:
Keynote Address: .QL for Source Code Analysis
srcQL: A Syntax-Aware Query Language for Source Code
• poorly researched topic
○ what people have come up with
from RefType c1, RefType c2,
RefType node, RefType adviceDecl
where
node.hasQualifiedName (" polyglot . ast","Node") and
adviceDecl . hasQualifiedName
("abc. aspectj . ast","AdviceDecl c") and
between(adviceDecl,c1,node) and
between(adviceDecl,c2,node) and
c2.hasSupertype(c1)
select c1,c2
$U = $I + $T;
FIND src:function WITHIN src:class;
Visualization:
• be happy if you can get colored code;
we are forever stuck in the never ending endtimes of the 80s
https://www.youtube.com/watch?v=C8--cXwuuFQ
Dom_inspector:
• a tool that can fetch and or modify DOM element information at runtime,
by interactively selecting an element { mouse }
• as far as im aware (2024), only browsers implement them
• very useful for prototyping and debugging
Topology_graph:
• network
• object
• database
Flame_chart:
• the type of chart that is used for execution stack visualization
• the 'x' axis means time
{
[#]
[#][#] [##]
[#][#] [task] [action]
[### init ###] [### opts ###] [#] [##] [##### thing #####] [quit]
[############################### main ###########################]
}
gource <options> <path> : git history visualization tool;
displays the source as a graph
and continously constructs it
according to the commits
— o <file> : save as video