Ubuntu Wiki

Ubuntu Opportunistic Developers Week March 2010 - Write Beautiful Code (and Maintain it Beautifully) - rockstar - Mar 4 2010

(02:02:28 PM) rockstar: Hi folks.  Apologies in advance for the Lernid users, but I'm not really a slide guy, so you'll just have to follow along.
(02:03:17 PM) rockstar: So, dholbach asked me if I'd be willing to talk about writing beautiful code.
(02:03:51 PM) rockstar: That puts me in a hard spot, since sometimes I write code that fell out of the ugly tree and hit every branch on the way dawn.
(02:04:57 PM) rockstar: As I thought about it though, beautiful code is a process.  It's iterative, and the things you find beautiful now will (probably) be ugly to you in a year.
(02:05:39 PM) yofell is now known as yofel
(02:05:41 PM) rockstar: So I began thinking about that process - this is what I'd like to chat about today.
(02:06:49 PM) rockstar: Since this is opportunistic developer week, I want to make this a story about opportunities.
(02:08:19 PM) rockstar: The scenario I'd like to start with is this:
(02:08:36 PM) rockstar: "You've been using Ubuntu and you're feeling very comfortable.  You're in an IRC channel when someone says 'It would be nice if I had an app that would...'"
(02:08:50 PM) rockstar: Uh oh.  There's not an app for that.
(02:09:23 PM) rockstar: But guess what?  You're an opportunistic developer!  This is an opportunity!
(02:09:44 PM) rockstar: QUESTION: <JayFo> will you be going over some tips for making ugly code better? :)
(02:10:08 PM) rockstar: ANSWER: Yes, as I said, making ugly code better is a process.  The process is the core of this talk.
(02:10:50 PM) rockstar: So, we're going to start a new project.  In this scenario, staying away from ugly code is easy, since there's no ugly code to begin with.
(02:11:32 PM) rockstar: When you start a new project, you should get a few things together.  First, you need some version control system (Renaming files to .bak doesn't count)
(02:12:06 PM) rockstar: You also should have an issue tracker, even if you haven't even released your code.  This may be as simple as a TODO file.
(02:12:59 PM) rockstar: Luckily, we have Launchpad.  Those Launchpad developers are awesome.  They do awesome things.
(02:13:56 PM) rockstar: You'll also want a style guide.
(02:14:40 PM) rockstar: Programmers have stolen the idea of a style guide from writers and journalists.  A style guide allows you to set some social contracts in how your code is structured.
(02:15:02 PM) rockstar: This is a must.  If you don't have this right now in your project, your homework is to go out and establish one.
(02:15:30 PM) rockstar: Everyone has different tendencies in their code, so code can get messy as soon as more than one person touches it.
(02:15:54 PM) rockstar: QUESTION: <ylynfatt> I assume when you say style guide you mean the same thing as "coding standards"?
(02:16:09 PM) rockstar: Yes, same idea.  You should have common idioms.
(02:16:47 PM) rockstar: Document this well.  It makes life much better when contributors come aboard.
(02:16:57 PM) rockstar: QUESTION: <JayFo> QUESTION: are there any good sample style guides to start with?
(02:17:21 PM) rockstar: Python (my favoritest most bestedest language) has a language-wide style guide.
(02:17:29 PM) rockstar: It's called PEP 8.
(02:17:42 PM) rockstar: http://www.python.org/dev/peps/pep-0008/
(02:18:23 PM) rockstar: Basically, it addresses where to put comments, how to name variables/classes/"constants"/functions/etc
(02:18:47 PM) rockstar: \sh kindly points out https://dev.launchpad.net/StyleGuides
(02:19:36 PM) rockstar: So, on the Launchpad team, there is a style guide that supplements PEP 8, and then we have a style guide for our javascript, etc.
(02:20:18 PM) rockstar: I don't personally like some of the standard styles in the Launchpad team.  If I wanted, I could violate those styles, but then no one would approve the code review, and I'd never get anything done.
(02:20:53 PM) rockstar: The "social contract" basically allows us all to come to the table with the same expectations for the quality of code.  That's what the style guide gives us.
(02:21:07 PM) rockstar: <somename> QUESTION: Kinda offtopic but is there a reason why space indentation is preferred to tab indentation in PEP 8?
(02:21:35 PM) rockstar: somename, the BDFL of Python has spoken.
(02:22:22 PM) rockstar: That question is actually quite on-topic.  Sometimes there's no other reason to have the rule than to just have a standard rule.  You can't have both, so there as a choice made.
(02:22:51 PM) rockstar: So put together your style guides.  They won't be set in stone.  In fact, they'll be quite fluid.
(02:23:03 PM) rockstar: The Launchpad team meets once a week to evaluate if style changes are needed.
(02:23:15 PM) rockstar: Just yesterday I proposed a change in style and everyone agreed.
(02:23:34 PM) rockstar: QUESTION: <theDtTvB2`MB> When there is a small bug that needs to be fixed real quick, I violate all the style guides and fix it as fast as I can. Does anybody have the same problem as me?
(02:24:35 PM) rockstar: I guess I don't know the specific situation, and sometimes you need to do some hacky things to get bugs fixed.  Your style guide shouldn't get in the way of your work.
(02:25:02 PM) rockstar: However, when you violate the guide, you're automatically making your code harder to read for others.
(02:25:30 PM) rockstar: This actually brings me to my next point (thanks for the easy segway).
(02:25:58 PM) rockstar: In whatever language you're working with, the code you write is not for the computer.
(02:26:20 PM) rockstar: The computer is going to take that code, translate it into something it understands, and then run it.
(02:26:43 PM) rockstar: The code you write is for humans like you and me.
(02:27:19 PM) rockstar: Remember that when you're writing the code.  Keep it in mind.  Read your code out loud.
(02:27:50 PM) rockstar: C-code, for me, is especially difficult to read aloud, but it helps me to see where something doesn't make sense.
(02:28:33 PM) rockstar: Since most documentation standards target US or UK English, your code should kinda make sense that way as well.
(02:29:50 PM) rockstar: Sometimes (as in the case of asychronous code) you won't be able to write your code left-to-right/top-to-bottom
(02:30:06 PM) rockstar: Use comments in those cases.
(02:31:38 PM) rockstar: Alright.  We have about 20 minutes left.  In about 10, I'd like to take and review some "ugly code" that some of you would like to submit.  Please pastebin your examples of "ugly code" and then post them in the chat
(02:32:11 PM) rockstar: Okay.  So let's look at another situation, one that is more common, and will probably help you to be better when you actually start projects.
(02:32:42 PM) rockstar: You're in IRC, and someone says "<App> is really cool, but it has a problem with <feature-x>"
(02:33:13 PM) rockstar: Opportunity awaits!
(02:33:40 PM) rockstar: Often, this is where I see "ugly" code, because it's not my code, and it's not in a style I understand immediately.
(02:34:05 PM) rockstar: If the project has a style guide, read it before sleuthing to fix the problem.
(02:34:11 PM) rockstar: If it doesn't, Thor help you.  :)
(02:35:18 PM) rockstar: After you're comfortable with reading the app's code (whether by style guide or fumbling around), find the code you want to work in.
(02:35:53 PM) rockstar: As you write your feature, explore the idea of writing a test for that feature.
(02:36:12 PM) rockstar: Many languages have great test frameworks that you can use.
(02:37:06 PM) rockstar: Testing helps you to avoid embarrassment when (not if) your feature breaks.
(02:37:45 PM) rockstar: Make sure, as you write your patch, that you're sticking with common coding conventions.
(02:38:15 PM) rockstar: When I say "common" I mean "common the surrounding source code" - Make the code consistent.
(02:38:58 PM) rockstar: Once you have your patch (and hopefully test), you're ready to show someone your code.
(02:39:15 PM) rockstar: This step is the most important.
(02:39:46 PM) rockstar: You're more likely to write ugly code when no one has to see it, and when you don't have to justify why it's ugly.
(02:40:40 PM) rockstar: I had a friend who worked as an intern on a proprietary mobile phone platform that said "You would hate this source.  It's terrible, because no one has to see it."
(02:41:00 PM) rockstar: Okay, so we submit our code for review.
(02:41:08 PM) rockstar: Does anyone want to pastebin their ugly code?
(02:42:28 PM) rockstar: QUESTION: <tgalati4> Question first:  Are there any Python style (say PEP 8) checkers?
(02:42:59 PM) rockstar: Yes.  On Launchpad, we use pylint (slow, annoying) and pyflakes (doesn't handle exceptions to the rule well)
(02:43:24 PM) rockstar: For javascript (my second favoritest language) jslint is what I use.
(02:44:09 PM) rockstar: Let's look at the "ugly code" here: http://pastebin.com/1jWRpKCG
(02:44:35 PM) rockstar: Thanks to theDtTvB2`MB for putting himself out there.  That's good.
(02:45:02 PM) rockstar: Okay, so this javascript code.
(02:45:35 PM) rockstar: Javascript is notorious for being a wild west "every man for himself" language.  It's easy to write messy code, it's easy to write code that leaks memory.
(02:46:10 PM) rockstar: So as a reviewer, I'm first going to ask what "r" on line 4 is.
(02:46:39 PM) rockstar: "r" doesn't tell me anything about the variable, what it contains, or what it's used for.
(02:46:55 PM) rockstar: Neither does "c" or "is_DM"
(02:47:21 PM) rockstar: That makes this code hard to follow.
(02:49:24 PM) rockstar: I also don't have very many comments.
(02:49:50 PM) rockstar: Line 53 is actually succinct and rather helpful.
(02:50:04 PM) rockstar: Basically, are we starting with the first item in the index?
(02:52:15 PM) rockstar: I also am not entirely clear on what the function returns.  It returns a few different things, depending on specific conditions.  A comment at the top of the function would go miles in helping understand what's going on.
(02:52:36 PM) rockstar: I rather like jsdoc, and having been using it in my javascript gaming engine I've been working on.
(02:53:17 PM) rockstar: By documenting, you help other young developers to start off knowing what the function is doing, and then they can use that context as they read the code.
(02:53:32 PM) rockstar: <theDtTvB2`MB> And now I starting to forget what some of these line do.
(02:53:54 PM) rockstar: theDtTvB2`MB, this is why we strive to write beautiful code.
(02:54:21 PM) rockstar: :)
(02:54:25 PM) rockstar: Any other questions?
(02:54:49 PM) rockstar: Let me point out a potential opportunity here: <tgalati4> Does Lernid have a search feature in the Session window?  That would help to jump to code.
(02:55:01 PM) rockstar: QUESTION: <theDtTvB2`MB> Does it need a rewrite?
(02:55:28 PM) rockstar: So, rewrites can be scary, especially when you don't have tests (and sometimes even when you do).
(02:56:15 PM) rockstar: Usually, when I get into code I wrote that I have forgotten about, I will take some time to sleuth the code, remind myself, and then document the code, and sometimes make slight changes (variable names, etc.)
(02:56:53 PM) rockstar: Sometimes code is unsalvagable, and you'll have to re-write it, but just be careful there.  You don't want to be KDE 4.0, do you?  :)
(02:57:05 PM) rockstar: <evrick> QUESTION: when does it makes sense to make code more generic (useful in many places). Or to make an abstraction to it?
(02:57:28 PM) rockstar: I would say that you should NEVER repeat code.  Never, ever, ever, never, ever.
(02:57:51 PM) rockstar: Sometimes, abstractions are harder to understand, so you'll have to "glue" that with good comments.
(02:58:23 PM) rockstar: QUESTION: <tgalati4> So can I find good examples of python coding style by doing:  grep python /usr/bin/* ?
(02:58:31 PM) rockstar: So, I'm not sure what that would give you.
(02:59:06 PM) rockstar: Bazaar's source code is awesome for seeing good coding standards as well as ways to make python perform better.
(02:59:44 PM) rockstar: They have some potentially difficult and crazy code that is commented with things like "we have to do this now, or the function won't return fast enough" and things like that.
(03:00:16 PM) rockstar: Any more questions?
(03:00:59 PM) rockstar: Thanks folks!