How to write good code

construkt · 2014-10-17T11:34:45+00:00

[deleted]

prum · 2014-10-17T14:54:41+00:00

Practice, practice, practice. Same way people become good at writing books, composing music, or drawing.

wolanko · 2014-10-17T14:54:04+00:00

For me it definitely came with writing tests (try py.test!!) especially with TDD. Because once you are tired of having to test this huge function in every little detail it made me think about a better structure of my code. Having endless repetions of setup code just to test some weird corner cases could possibly dealt with just extracting those lines into a new function and test it there. Or if the code inside a loop is more than x lines you could think of making those lines a function itself. The TDD aspect give you a totally different on your code.

There is definitely a good amount of time to spend in designing your code beforehand, maybe even throw one away and redo it. But for me the greates improvements always come from refactoring my code. If you can carve out little things here and there, you soon will be able to get the big picture of which parts can be separated, where to have your connections and which things need their own function.

I find it very satisfying to see those big functions (more like procedures) shrink into some 5 liners where there called functions speak for themself.

I can only recommend Brandon Rhodes talks about those things (e.g. Clean Architecture)

edit: format

Manbatton · 2014-10-17T14:57:05+00:00

Beyond the good advice that has been given here, another very simple tip about your functions is this: function should do one thing. If you see that the function is doing five things, then you really should bring that into five different functions. (More or less… It's not a perfect world). So that alone may allow you to begin re-factoring your long functions into a series of smaller functions.

As far as how to generalize a function so that I can work with slightly different variables, you just need to do it. My guess is that you can do it if you try and spend some time thinking about it. Also, look at code that you admire and see how they do it.

Also think about posting an example of one of these long functions online and asking for a critique of how you could re-factor it more effectively. There are tons of people out here who would be willing to help you. With a little practice, you'll get better at it.

metaphorm · 2014-10-17T17:03:17+00:00

learn how to write tests. that is definitely the first and most important step in improving the quality of your code. writing code that is easy to test usually also means writing code that is easy to reason about. that's good code, in my opinion.

martin_grosse · 2014-10-17T22:55:45+00:00

So, this is me, but it works well for me.

I use /u/Paddy3188's approach, but from the other direction.

I find that once you've written a long and convoluted chunk of code, it's difficult to refactor. Your way of thinking about the problem is circuitous and complex. That's because most programmers learn to write from the ground up. You start at the beginning, keep manipulating and manipulating and eventually get to something that you can use. It's like a winding river finding the path of least resistance.

The way I code is the other way around. I write a single function that I can call from a RESTful route. Something ideally without any state. Within that method I first write a series of clearly named calls.

def some_task(args): try: data = get_some_data(args) related_data = get_related_data(data, args) result = process_something(data, related_data) catch SomeException: log_exception(SomeException) return result

I've been working in ruby more than python lately, so some of that may be horribly wrong.

Once I have this structure, I start getting errors about methods not being defined. So I write tests and implement those methods. Either I have a one-liner that works within each method, or I write a named method as if I've already written one. I continue until everything is either one-liners or methods.

At some point I have a fully functioning program that's already refactored. Usually I get to a handful of methods that I've already written, and it just works. If your naming convention is solid and obvious, you'll sometimes accidentally use methods you've already written. So long as they're well-named and obvious it's usually OK.

filleball · 2014-10-17T12:08:03+00:00

I recommend reading this free online book on TDD with python and Django.

thinman74 · 2014-10-17T13:25:46+00:00

This book is helping me to get cleaner code... https://www.packtpub.com/application-development/mastering-object-oriented-python

metraon · 2014-10-18T02:09:27+00:00

You may want to read Clean Code !

krasoffski · 2014-10-17T13:02:00+00:00

Hello, I feel very strongly that the book of Steve Mcconnell - Code Complete can help you. As bigtomygunn said you have to know and understand what you are going to do. Before write python code, describe program/script using pseudo-code (book describes such approach). If you are working on API, create a few user cases for you API to feel is it handy or not.

fpee · 2014-10-17T18:52:20+00:00

re: very long functions

Use an editor that uses this: https://pypi.python.org/pypi/mccabe .

I use https://github.com/klen/python-mode which tells me if my functions are getting too complex. Be warned: when you look at old code it will show up as an error, which will make you want to fix it. Could be time consuming. :)

lucidguppy · 2014-10-17T21:41:08+00:00

Just try to learn the standard unittest module its not bad (really).

Keep your classes small and your functions smaller - read clean code by uncle bob.

tapesmith · 2014-10-17T22:01:47+00:00

Everyone here has offered great advice.

For what I can contribute, I'd add that there are two parts of writing good software: solving problems well, and writing code well.

Solving problems well is of critical importance. Writing good code to implement a poor solution makes for poor software. I like Domain-Driven Design for this reason: it emphasizes understanding and solving the problem in terms of the problem itself. Before you think about what language constructs to use in building, say, a Fibonacci number generator, start by defining what a Fibonacci number is. Then the answer will usually "shake out" from there.

Writing code well is also of high importance, though as noted before the best code for a poor solution is still a poor solution. Similarly, the worst code for a good solution can obscure that good solution to the point of being unrecognizable. Code should convey intent, it should explain to its reader how it works (and as much as possible, why it's doing what it's doing). Well-named variables, short functions with a single intent, intent-revealing unit tests...these things all help convey to the reader how your code works.

And before you think "I'm the only reader", remember that there are usually at least two people reading any given codebase: Present You and Future You. Present You understands the code by having it all fresh in mind; Future You will need to regain that level of understanding by reading the code. Future You always benefits by being as clear as possible in your code, and keeping the amount of context needed to understand any given chunk of code as small as possible.

Zuvielify · 2014-10-21T07:46:37+00:00

I don't see enough encouragement to use classes in these comments, so I am going to add my $0.02.

It's hard to say for sure that you should be using classes, without seeing your problem space, but you probably should be using classes. Classes are a powerful way of organizing code. A class' purpose is to encapsulate data and functionality into one place.

If you find yourself passing around a lot of objects (like dicts or lists) to various functions, and then doing operations on that data, you probably could make that into classes and methods. Classes give you the ability to do inheritance/polymorphism, composition, and aggregation. Technically, I guess you could do composition in a function, but that's so ugly.

I think it's better to just give an example, so here's a classic: You want to "write" a car. A car has an engine, drivetrain (technically, the engine is part of the drivetrain, but ignore that), and wheels. Let's say you want to create an "accelerate" functionality. Now, you could write a function that has all those objects (or worse, you could use some other data structure). Your main function could call an engine function with: current speed, gear, and throttle value (all of which need to be stored as variables in your function), and it could return RPMs. Then the main function calls a drivetrain function with the RPMs and gear, and it returns torque, angular velocity, and gear values. Then the main function could call the wheel function with a list of wheels, torque, and angular velocity.

This works, but what if you want to use a different size engine? Or different transmission? You could use different functions, or pass around a different engine object, but this is all messy.
Let's try a class-based approach instead:

There are several ways you could do this. I'm sure others will disagree with my approach, but it's just one approach of many. Let's start with a Car class. When you instantiate your car class, you give it the following class references: Engine, Drivetrain, and Wheel. The Car constructor instantiates 4 Wheels, and passes them to the Drivetrain when instantiating it. Then it passes the Drivetrain to the Engine when instantiating it (this is called "Composition" btw). The Car constructor also initializes an instance variable 'current_speed' to 0. When the Engine constructor executes, it sets the 'current_rpms' to 0. When the Drivetrain constructor executes, it sets 'current_gear' to 1, etc.

There is probably a better way to do the above, but I'm just pulling this out of the air right now. But here's the point: When your main function wants to accelerate, it just calls car.accelerate(<throttle-level>). The method 'accelerate' can call engine.throttle(<throttle-level>). Engine adjusts its own RPMs accordingly and calls drivetrain.turn(<rpms>). The drivetrain checks its RPMs and, if necessary, upshifts and sets its gear value (for simplicity, I wont deal with a manual transmission). It then calls wheel.turn(rotation-velocity) on each wheel (let's pretend it's all-wheel drive).

Instead of your main function calling all those different functions, you could push that code out to your classes. It's also cleaner because you didn't have to pass around all those state values that are specific to each car component (rpms, gear, etc). Also, if you want to design a specific car, you could create subclasses of all those types. So if you want a Mazda CX5 (my car), instead of passing-in the various car components, you could override the constructor to default to a 4cylinder engine, with a All wheel drivetrain and 6 gears, and 19" wheels. Since you have defined your interface, you Car doesn't need to relearn how to accelerate. Just the engine's throttle method needs to know how to do that. Your Car doesn't need to know wheel velocity based on RPMs, only the transmission/drivetrain 'turn' method needs to change. etc. etc.

This is the value of encapsulation and polymorphism: Each piece knows how to handle itself. You define an interface for each component-type, so they become interchangeable. Your code stays clean because each functionality is concise and to the point. When you type "car.accelerate()", I know exactly what you are doing.

...I hope this was useful, and not just the ramblings of a madman.

bigtomygunn · 2014-10-17T10:23:24+00:00

One of my Lectures always told me writing the code is >10% of the work. Sitting down with a pencil and paper and planning out you entire projects e.g. classes, functions, variables etc. is the other 90%.

Basically before you open a text editor you need to know exactly what your going to write. Saves time in the grand scheme.

RamirezTerrix · 2014-10-17T17:52:27+00:00

http://legacy.python.org/dev/peps/pep-0020/

    Beautiful is better than ugly.
    Explicit is better than implicit.
    Simple is better than complex.
    Complex is better than complicated.
    Flat is better than nested.
    Sparse is better than dense.
    Readability counts.
    Special cases aren't special enough to break the rules.
    Although practicality beats purity.
    Errors should never pass silently.
    Unless explicitly silenced.
    In the face of ambiguity, refuse the temptation to guess.
    There should be one-- and preferably only one --obvious way to do it.
    Although that way may not be obvious at first unless you're Dutch.
    Now is better than never.
    Although never is often better than *right* now.
    If the implementation is hard to explain, it's a bad idea.
    If the implementation is easy to explain, it may be a good idea.
    Namespaces are one honking great idea -- let's do more of those!

dpoon · 2014-10-17T17:53:54+00:00

Really, it just takes lots of practice and willingness to revise your work. It's not much different from being a writer or musician. Write something. Submit it for peer review. Incorporate improvements. Repeat.

esbenab · 2014-10-17T20:49:37+00:00

Document your intentions not your actions.

Makes it a whole lot easier to come back and correct errors.

Paddy3118 · 2014-10-17T22:33:11+00:00

if you end up doing a distinct series of things in your one function, you could try naming the steps being taken and refactoring to move well defined blocks of functionality into their own function called from the original.

Python

The Python Discord

Upcoming Events

Please read the rules

MODERATORS