Ask HN: What code do you consider as clean code? | Hacker News Reader

Ask HN: What code do you consider as clean code?

5 pointshamedb15 comments

obviously this is something debatable and subjective but there's always some common basis that everyone agrees on. do you have any good examples of code you wrote or saw on Github that you consider as state of the art code? what makes it so great? if you are reading someone else's code how do you want it to be written/structured (preferably JS examples)

View on HN

> but there's always some common basis that everyone agrees on.

I am really curious what this is because I have been with 4 organizations now and despite all doing things very differently, they insist that they are doing things according to "industry standard."

I have even had a few cases of two senior devs reviewing my PR at the same time and going back and forth to tell me to revert what the other dev had me put in, with both coming from prestigious companies.

>> had a few cases of two senior devs reviewing my PR at the same time and going back and forth to tell me to revert what the other dev had me put in

As a senior guy reviewing code I’ve asked for reversion of stuff i made the dev put in. On more than one occasion. Nobody’s perfect.

I admit that after a few cases of that I realized I needed to rethink code reviews and became more mindful of distinguishing between things that really needed to change, things needing explanation, and things inspiring overzealous pedantry. Made code reviews much less time consuming.

for the "common basis" part I'm referring to commenting code/ using descriptive variable names/ breaking mega large files into smaller ones...

things that developer do not agree on include choosing between (object-oriented, procedural or functional code)

the debate of isolating small bits of code regardless of the paradigm used. how many "code components" can be created without making the follow references game so crazy that you can't even understand the code flow and where you even started reading the code. are small code duplicates really that bad or over componentizing is a bigger issue that tries to solve the first one?

things like that...

I didn't work for large company before so was wondering if you saw any consensus/ agreement patterns between senior developers in these type of debatable things especially when writing JS because of it's huge flexibility.

Steve McConnell covers this in "Code Complete". Iirc, a lot of the book is based on actual research done, not anecdata.

https://en.wikipedia.org/wiki/Code_Complete

will take a look.

but it seems it focuses a lot on TTD/unit testing and integration testing not my thing.

I hate testing and never understood why they created this most complex todo list in the first place?

just write what you are going to do it and don't worry no need to check everyday if the code still exist or not.

why run an automated check every single day of the same code. not to mention the time wasted on mocking and creating fake data.

sorry a bit off topic but I really hate tests! would need to understand why some still defend TTD...

I've enjoyed reading the Guacamole client code (JS): https://github.com/apache/guacamole-client/blob/master/guaca...

Clean and consistent formatting, detailed comments, sensible modularization -- and it works well

oh thanks for giving a great example definitely well written code. been reading this https://github.com/apache/guacamole-client/blob/master/guaca...

don't you find that comments are taking a lot of space more than the actual code or do you think this is what a takes to avoid confusion. I found that single line comments are much better, compact and enough to explain what is happening as opposed to those multiline comments that take so much space.

The multi-line comments follow JSDoc syntax, which many IDEs can parse to give the developer useful suggestions. https://jsdoc.app/about-getting-started.html

One of the first thing to pick up that it's likely agreed upon by everyone is to give meaningful names to variables:

// GOOD

let fullname = 'John Smith'

// BAD

let f = 'John Smith'

There is a balance between two good things: (1) understandable names and (2) compact code that fits on the screen and avoids excessive line breaks. As opposed to DesignPatterns style names I often like names like FunctionThatThrows. I love writing tests where the name of the function says outright what the test does, even if the test name is 40 characters long (not like you're going to type it again!)

People get in a lot of trouble when they try to write descriptive names for everything.

It was one of the most interesting things in the Lenat/Guha book on Cyc that people get fooled by labels that look like natural language. If you really have a database of unique concepts and try to attach meaningful labels you are going to have an increasingly hard time when n goes past 1,000,000. Wikipedia does about as well as can be done. There's something to say about lowering your cognitive load and using names like "that", for instance

   return this.add(that)

Depends entirely on the context, ie. what's the scope of `fullname`.

If this is a variable in a 20LOC func, f is completely sufficient, easier to type, easier to read.

In the other extreme, names can also be too meaningful: ´ThingMessageRelayAdministratorMiddlewareComposer` or `storage_access_administrator_storageshelf_listview` are jacked full of meaning, and about as useful as a hammer without a handle.

Then one year later you have to play archeologist and figure out the hard way what `f` is used for. And I also find it much more difficult to write code like this in the first place because it forces me to memorize the purpose of every identifier.

Not sure how "easier to type" is relevant - aside from Notepad pretty much every editor offers some completion feature. I'm definitely a fan of longer identifiers, though abbreviated where it makes sense and using short words where possible.

If you are basing off of mathematical notation, f g and h might make sense for identifiers for very generic functions, especially if tin are implementing the chain rule somehow. I would find more verbose names harder to read because the notation was already ingrained. Same for those who name their looping integers something other than i or j.

> and figure out the hard way what `f` is used for.

In a 20 LOC function, that takes me about a second, if that long.

> aside from Notepad pretty much every editor offers some completion feature

It's still easier to type `f` than `fi` + leadkey + N or whatever the editor uses. Bonus points if the first prediction is wrong, or ambivalent.

And the more important reason is "easier to read", especially in long expressions;

    for e := getFirst(); e != nil; e.Next()

is much easier to read than

    for currentElement := getFirst(); currentElement != nil; currentElement.Next()

Finally, not only the name itself, but also it's length should convey meaning. If I see a variable like `currentElement` in my code, I immediately know that it probably lives beyond the scope it is defined in. If I see a variable named `c` I know that it is a short lived throwaway.

yeah everything agrees on the necessity to chose meaningful/short/descriptive/concise names.

but I was asking if there's anything to keep in mind when building large complex code.

- how long or short are your functions?

- what do you comment?

- can you actually use only pure functions?

- how large are your files?

- how do you manage 3rd party dependences or do you don't use any?

- how do you mange bundle size and enforces code quality?

- when to break a function or break a file into smaller parts?

- do you create functions that call only other functions or each function should have some procedural code?

giving code examples of a well written code snippet would be so helpful!

Reply on news.ycombinator.com