Skip to content

README.md

Latest commit

 

History

History
136 lines (78 loc) · 5.99 KB

README.md

File metadata and controls

136 lines (78 loc) · 5.99 KB

« . . .  In the beginning was the Word » 

Code organization

  Three Elephants of code org

Denomination of titles and their classification (that imply domain partitioning) is a pivotal but underrated activity in every exploration.

In software, names with categories, which smoothly guide developers through the design and make development intuitive, are often taken for granted.

O t h e r w i s e

one wading through the thorns of pathetic names, code labyrinthine (or flats), and abatis of documents will curse complexity, learning curve, technologies, and fate, but at last the naming.

🐘 Categorization

Categorisation (aka classification) is more profound than breaking collocations with sentences, and building the folder hierarchy  —  it frames abstractions.

If enthusiasts with magnifying glasses could logically group swarms of wretched boulders in far space and paltry insects, it wouldn't be such a burden for unique by-nature software entities.

The challenge is to lay out accurately. Our imagination tries to mnemonically align doubtful and even bizarre names to the right meanings and aliases, but takes on trust their structure.

___________
As a negative experience, GitHub is full of shallow folders and huge lists, even for corporate projects. Namespaces of frameworks and languages may look like a verbal dump.

Tags

The only limitation of categorization is the strict tree graph. Tags may rationally dissolve it, though frameworks and IDEs provide limited support for them.

How to name  . . .

AS USUALAS CRUCIAL ...

The prevalent naming is a derivative of the development, which

❌ rests on programmatic "false-domain" made of Helper.Get(..), Utils.Do(...), Service.Find(...), and other supports,
❌ leaves "construction waste" of temporary names, placeholders,
❌ spreads umbrella terms and horizontally swelling folders,
❌ spawns long names and shallow categories (AddTableReservationInRestaurant(..)),
❌ interferes with existing domain and programming naming,
❌ contains jargon and slang, or terms, dubious in other tongues or cultures.

  O RLY? Variable name. The hardest part of coding

The naming of libraries, packages (assemblies), folders, classes, methods/functions, and even non-public vars must be a №1 challenge and involve the whole team👪 in discussions.

The inevitable and heavy expenses will pay off with the formation of lingua franca throughout the team and project, along with ...

  • shared comprehension of a domain, which binds teams,
  • genuine design and self-descriptive code,
  • inspiration for driven design,
  • base for writing and reading the documentation📒,
  • less tension to get into a project for newcomers,
  • comfy navigation in the source code (beginning from CTRL+F).

      👪 The team means not only developers and managers but customers, testers, and end users.
      📒 reqs/specs, DoU, meetings protocols, and primers - hard to follow but easy to misunderstand or forget

It's an ingredient of successful domain-driven design (and vice versa).

What's next

Practice

/// to be continued...

Wrapping up

  • Even top consonant teams under time pressure and brakes on perfectionism would rarely be proud of their naming implementation.
  • The naming (akin to code quality) will never be perfect, but efforts to improve it must be honest and continuous.

Appendix. Learning from others

Hall of Fame

🥇 Historical S[E]QL commands.
🏆 Bread crumbling for navigation  —  win for both the idea and name

___________
Audience choice Price goes to Mrs. Grace Hopper who suggested tongue (English) semantics for programming (so natural now that one can't estimate).

... TO BE CONTINUED ...

Legacy

🚧 ... to list ... 🚧

World of ambiguity

"Generals"

As programming evolved, a mass of general terms had to be given. Some, as object or bug, are relatively univocal hits — others shade higher-level notions or interfere with them:

Application, solution, interface, exception - to name a few.

Bug or Fix?

Tickets titled Bug mean not their introduction but the repair.

Exception or Error ?

Many languages (C# there) use this term for errors to throw, though its meaning can sound even opposite  —  allowance.

Curtain of grace (opened)

👑 And the winner is ... dirty in miscellaneous languages and APIs as the trait of a modified object.

SQL COALESCE is nothing but FirstNotNull

🍅 🍓

🍓 🪱 longness

  • 'Emoji' defines pictograms overall, while being only a subset.
  • "Icons" are .. eh .. a bit blasphemous.

🗼"Tower of Babel" award for naming in different alphabets. (Unless it's a highly localized domain or business.)

First-class citizens for functions or other techniques have a discrimination flair ...

___________
🔚 .. 🌙 ... 2024-2026.. 📂README+
// The collage uses the Hindu version of World Elephants.