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
thing.thingdoer().clone().unwrap(). unwrap().unwrap().parse::<other thingy>().unwrap().iter().collect()is as good as it getsI had a hand-written coding test in high school with a simple sort implementation for airline seats. I didn't want to do all the writing the obvious solution required so I came up with a really short and parsimonious solution. The teacher asked me to walk him through and had me present it to the class. He asked me how I came up with it and I told him "I didn't want to write 10 lines of code." and he had the biggest smile.
- agree, but also try to minimize newlines to keep more code visible at once
- agree
- disagree
- disagree
- I would say python is good for cross-platform shell-like scripting, but no serious systems
- disagree (within reason)
- I try to avoid meaningless variable names altogether, even with iteration counters in for loops
- no opinion
- WRONG
spoiler
ALSO WRONG
(except in html or javascript)I have absolutely written code that looks like
if () {} else {}So maybe my judgement on curly brackets shouldn't be trusted
That is how I like to do it. Otherwise everything just takes up to much vertical height and I get sad
Quick rules:
Quit trying to be clever, you're not smarter than the compiler
Make your functions smaller. No, smaller than that keep going.
Don't comment about the what your code is doing, i want to know why it's doing it. Write tests to document the how
Run the litter before you make me read your code
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.
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.
similarly, doc comments in 2024 need to be completely rethought.
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.)
In Rust, we don't say "I love you", we say
Pin<Box<dyn Future<Pin<Arc<HashMap<Arc<String>, Vec<Arc<Mutex<Box<dyn Future<u128>>>>>>>>>>>and I just think that's beautiful!I like very DRY code that is self-documenting, has a unified style, and has good documentation.
spoiler
Agree
