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

https://news.ycombinator.com/item?id=29956499

by hamedb • 5 years ago

5 15 5 years ago

news.ycombinator.com

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)

MattGaiser• 5 years ago

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.

hamedb4• 5 years ago

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.

no-s• 5 years ago

> 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.

giorgioz• 5 years ago

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'

usrbinbash2• 5 years ago

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.

alpaca128• 5 years ago

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.

PaulHoule• 5 years ago

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)

hamedb4• 5 years ago

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!

gabrielsroka• 5 years ago

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

hamedb4• 5 years ago

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...

joshink12• 5 years ago

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

hamedb4• 5 years ago

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.

joshink12• 5 years ago

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

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

Related Stories