DEV Community

Writing Beautiful Code

Andrew Davis on September 24, 2018

Because programming is a technical profession, we often approach it without thought to design. Code is for getting a computer to do what we need, w...

Read full post

Martin Riedel • Sep 24 '18

For me it worked best if i treated the code i write not as something i write for a computer to execute. I treat code as a sort of documentation for other humans that might end up maintaining whatever i wrote.

In that regard, i value your first point a lot. A good suite of tests has proven to be invaluable (for me) when i had to add/refactore something in code i either didn't write or wrote more than 2 days ago - because i may or may not have any memories about that ;)

Marcus M • Sep 25 '18

Regarding 1st paragraph: That is an great way to write your code. I'll try to do the same, but sometimes end up with long function names.

How do you handle this?
Are you for or against abbreviations?

Martin Riedel • Sep 26 '18

When there is an 'and' or 'or' or something like this in the function name, i'll split it in two. Because obviously there are multiple concerns handled there.
If they are only long, i'm fine with that. Most of the time, one of my colleagues has a shorter suggestion in the review anyway :)

I'm not a huge fan of abbreviations - it hugely depends on the business domain and whether or not these abbreviations are kinda well known or not.

Andrew Davis • Sep 25 '18

Unit tests are the best!

Daniel • Sep 25 '18

If you want to make your code even more beautiful:

$validateEmail = filter_var($emailAddress, FILTER_VALIDATE_EMAIL);
$validateMessage = strlen($message->text()) < 1000;

if (!$validateEmail || !$validateMessage) {
  return false;
}

return true;

would be:

$isEmailValid = filter_var($emailAddress, FILTER_VALIDATE_EMAIL);
$isMessageValid = strlen($message->text()) < 1000;

return $isEmailValid && $isMessageValid

(PHP is not my first language, so bear with me if there are missing brakets somewhere)

Adam Crockett 🌀 • Sep 25 '18

Magic number

Daniel • Sep 25 '18

I said, "more beautiful", not "perfect" :P

Adam Crockett 🌀 • Sep 25 '18

Exactly, prettiest is perfect. One semi colon and a constant away from perfection and we can close this thread. Haha sorry I know this isn't a peer review, old habits and all that.

Daniel • Sep 25 '18

Ah, yes! Semi colons... that thing. xD

Adrian B.G. • Sep 29 '18

This will not work in a real project, most likely you will have to provide a message on why exactly the invalidation failed.

One liners are always on my radar on "smelly code", they usually lead to nasty problems.

Andrew Davis • Sep 25 '18

Good call! I’ve seen several recommendations for using is/has in Boolean variable names.

Daniel • Sep 25 '18 • Edited

Well, is/has is a convention. In Ruby it is common to use "question mark" instead.

But, more importantly, I would not use an imperative verb to name this boolean variable.

Imperative would more appropriate for methods (or functions) that have side effects. In this case, you are using the variable to store the result of a computation.

Jason C. McDonald • Sep 24 '18 • Edited

Great tips! While I still advocate intent-commenting (won't go into that yet again here), I think these principles are superb! (+10 to style guides.)

Nice rule of thumb to go along with this: the "what" of your code should always be clear without comments.

Andrew Davis • Sep 25 '18

I agree that comments are necessary, depending on the circumstance. Overall though, for standard CRUD operations, they can be unhelpful.

Btara Truhandarien • Sep 25 '18

Not just beautiful code, but overall design that scales, performance wise and cognitive wise. For many developers' day to day, it is not in the logical aspect of programming that is difficult (least what I've seen), but it's in the creation and choice of design

Tim Dwyer • Sep 24 '18

Spot on! Obviously form should always follow function but form should always receive proper attention as it clarifies intent and helps create trim, efficient code. Thanks for the standards fixer link.

Michael • Sep 25 '18

After some recent discussions with co-workers I sort of changed the way I wrote code, fewer comments and more writing code as a story. Make it understandable and readable the way it is, only commenting when you have something exotic or very detailed in the way the code works (which should be rare). Its helped me make things simpler and break things down more, I still find myself needing improvement but this was one I hadn't thought of and decided was needed.

Andrew Davis • Sep 25 '18

I think we never stop learning to code better. I always feel like there are even better ways to write it. I would like to see even more opinions about beautiful code so we can all share ideas!

Darryl Norris • Sep 24 '18

An interesting point of keeping the function small it's that you might be able to reuse that function later on. On another hand, I have experience that the complexity of the code sometimes increases by writing small functions, because of similar processing needs to happen on different functions that they are isolated from each other.

I think in the end there has to be a trade-off between performance vs. keeping the functions small.

Andrew Davis • Sep 25 '18

There’s always a trade off, but I think in general coders are more inclined to make functions too big than to make too many functions.

TheAutismDada • Sep 25 '18

Love the tips. For me, beautiful code is something you can look at and within a second understand the flow of the code. When it is structured correctly you don't have to know exactly what the code does to understand the flow.

That's just my definition anyhow. Thanks for sharing

Andrew Davis • Sep 25 '18

I agree! Everyone hates going back to code that can take hours to understand what is happening. Beautiful Code is about reducing that time down to seconds and minutes.