I recently had to deal with debugging chatgpt code, and though it was written clearly, it just seemed so ugly and hard to read to me. So I started to think about what I like and what I don't like when reading code. My personal guidelines for beautiful code are:
- space out code into functionally similar chunks. That way it's easy for my eyes to separate the steps of the code. (Often this is code that is only used once, so there is no need to put it in it's own function)
- comments are for clarity, and too many make clarity worse.
- similarly, doc comments in 2024 need to be completely rethought. I already have the actual documentation open on my screen most likely, no need to put the same information in your code. (yes, I know that java and others generate documentation from doc comments, and I don't like it)
- functions should be ordered by order of execution. Reading down the code should be like reading a book, telling the story of the code's execution. For an OOP language this should pretty well line up with layers of abstraction as well.
- python should be wiped from the face of the earth.
- self-documenting code (which is to say code with very long variable names) is bad practice. Once again, the code should be able to be read like a book, you wouldn't name the protagonist of Lord of the Rings 'Ring_barer_to_mordor_hobbit' just name variables something memorable and useful and move on.
- of course, the opposite, variables just named something meaningless like 'a' should only be used in the most limited of scopes. Loops, lambda functions, etc.
- There should be consideration for how the code flows on the screen
- curly brackets in C-like languages should always have their own line, with the exception of the start of functions and short if/else statements.
I don't know, these are just things that I have noticed I like to see in code. This could be the ravings of a lunatic as well.
spoiler
a tab is 2 spaces
When it comes to the curly brace placement holy war, I'm partial to BSD/Allman, but I don't really mind K&R. I do mind if the two styles are mixed interchangeably within the same codebase.
That being said, doc block comments should fucking convey something. If you're writing comments like this:
/** * Get the value of X. */ public String getX() { return x; }...I will find you and I will sic
on you. Of course, find me a CS grad who can string together more than four words in a commit log message (let alone a source code comment), and I'll call you a damn liar.
As much as he's a problematic, misogynist boomer doofus, Bob Martin was on the right track with Clean Code, even if it was really just a compendium of works by Fowler, Feathers, and so forth.
Rationale on the snark re: official documentation versus doc-block comments: the further it gets from the code, the more likely documentation is to become out-of-sync with what is in the code itself. If a doc block comment contradicts the code immediately beneath it, that's a simple fix. If a Markdown doc in a separate section of the project drifts out-of-sync, that's more difficult to catch. And yeah, Java, C#, PHP, etc. can generate IDE "help" text (e.g., IntelliSense popup info) in real time based on those doc blocks, as long as you're using the right tagging mechanism. If you're including hints about validation constraints or which overloaded constructor/method/whatever is supposed to be used in which situation, that can save your API consumers a lot of headaches.
Pure Web-based JavaDoc "documentation" is absolute ass, though; it nearly always lacks any useful context to explain some of the class/interface hierarchies that are in play for a given package. Still semi-useful for type hints at the IDE level, though. (Well, in a good IDE, anyway... That's a different rant.)