13 ms·

Thoughts on being a programmer

235 points by earnubs 14y ago

tokenizer 14y ago
Be yourself. Code for fun. There's hundreds of ways to write the same thing, don't be a dick about your way, but stand up for good practices. Respect those who accomplish great things, because it was a lot of work, even if they say it was a weekend practice, they took a lot of time to get to that point. If you code correctly, one line changes are possible. Learn to desire success more than you fear failure. (I like this one) Don't become the old people you hate, always try to learn new things, no matter how alien. Who cares if you're coding on production live? Right? Right? Comments are for the weak, tracing and prototyping code is not. Mistakes are inevitable *It's hard being the smartest person in the room sometimes, wear it with humility rather than pride. My version of the list. This was fun!
- nickolai 14y ago
  >Comments are for the weak, Care to elaborate on this ? Commenting code is bad ? Or did I miss the irony ?
  - recycleme 14y ago
    I've met a few senior level programmers who frown on detailed commenting (or commenting at all). I cannot wrap my head around this since I consider it best practice to comment. A reason given to me was that "it takes up too much time to comment and when you make a code change you need to make a change in the comments as well." To that I say, so what! I would like the future me (or the future programmer) to have full knowledge on what's going on in the code.
    - wreckimnaked 14y ago
      There's some debate on this: http://queue.acm.org/detail.cfm?id=1053354 http://queue.acm.org/detail.cfm?id=1053354
    - creativename 14y ago
      I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.), but in general I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does". I even find that when I write comments to explain what a specific method is intended for, it helps me avoid violating the single-responsibility principle. If I clearly spell out what I'm trying to accomplish, it helps keep me focused. To those who say that the code should be elegant enough to be read on its own, there are some cases where the business logic involved is really what needs to be explained. At the same time, what is elegant and concise for you may appear obfuscated and confusing for someone else. You may argue that they should know all the techniques that you know, but that's just the reality of working with others sometimes.
      - lawn 14y ago
        > I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does". There are good uses of comments, but there are also bad ones. From Coding Horror [1] an example: '************************************************* ' Name: CopyString ' ' Purpose: This routine copies a string from the source ' string (source) to the target string (target). ' ' Algorithm: It gets the length of "source" and then copies each ' character, one at a time, into "target". It uses ' the loop index as an array index into both "source" ' and "target" and increments the loop/array index ' after each character is copied. ' ' Inputs: input The string to be copied ' ' Outputs: output The string to receive the copy of "input" ' ' Interface Assumptions: None ' ' Modification History: None ' ' Author: Dwight K. Coder ' Date Created: 10/1/04 ' Phone: (555) 222-2255 ' SSN: 111-22-3333 ' Eye Color: Green ' Maiden Name: None ' Blood Type: AB- ' Mother's Maiden Name: None ' Favorite Car: Pontiac Aztek ' Personalized License Plate: "Tek-ie" '************************************************* Now imagine something like this exists for every function and you're reading the source code... Annoying. Others are less extreme of course, but repeating the code in comments is bad and even harmful if you forget to update the comment as well as the code. DRY is a good principle to have. Of course "all comments are bad" is simply wrong, comments are essential to explain decisions or non-obvious snippets or gotchas.
    - arethuza 14y ago
      I tend to get a bit upset if code has comments that basically just describe what code is doing rather than why. Stuff along the lines of: // Increment the total total++; // Execute our SQL query var result = query.execute(); Seems to happen a lot with developers who use comments to "sketch out" code (not a bad thing) and then leave the comments in place when the actual code is written.
      - flatline3 14y ago
        I prefer code where I can skim the comments and see the major plot points, at a glance.
        dllthomas 14y ago
        If you need to skim the comments to see how a function is doing what it's doing, the function is too long.
        flatline3 14y ago
        When it can take 3-4 statements to perform a single logical operation, there is still value in summarizing each block with a comment, even if the function isn't "too long".
        gnaritas 14y ago
        That's what function names are for. Comments don't need to summarize. A useful comments says why code is this way, it doesn't summarize or repeat code.
        flatline3 14y ago
        > That's what function names are for. A single function for every 3-4 line operation would result in incredibly disjointed code, and would require more explicit documentation of invariants because that function can now be called elsewhere (at least inside of the given translation unit). > A useful comments says why code is this way, it doesn't summarize or repeat code. That's nonsensical. Why wouldn't you want to abstract the complex?
    - flatline3 14y ago
      > I've met a few senior level programmers who frown on detailed commenting (or commenting at all). If they express those views, I wouldn't call them senior. Commenting is necessary to express invariants, and to summarize complexity that would otherwise require each reader of the code to understand the code itself in depth. Those are actually closely related things. Very few languages are capable of succinctly expressing sufficiently detailed invariants. Some are better than others -- maybe they support Maybe monads instead instead of possibly-NULLs. However, it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be. Failing to express those things means that any future reader/maintainer will be forced to trace your code, in its entirety, to reverse-engineer how it is probably supposed to work. In many cases said maintainer can never know for sure without tracing your code and ALL code that calls your code -- otherwise, any change to that code could break undocumented behavior that other code relies upon. Anyone who advocates against comments is justifying laziness, and they're wrong. The only supportable argument for not commenting is if a language is sufficiently powerful and succinct enough to express all the invariants normally expressed through comments, as well as being readable enough to permit a future maintainer to understand the design of the code without requiring them to spend an undue amount of time studying its inner mechanics. I'm not aware of such a programming language.
      - Ralith 14y ago
        Dependently typed programming languages can do the "express all the invariants" bit. Readability is an open question, though.
      - rimantas 14y ago
        “Don’t comment bad code—rewrite it.” —Brian W. Kernighan and P. J. Plaugher Is that senior enough for you? > Anyone who advocates against comments is justifying > laziness, and they're wrong No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself. To anyone interested I recommend to get a copy of "Clean Code" and read the relevant chapter. IIRC "Code Complete" mostly agrees.
    - julsonl 14y ago
      The issue I have with commenting is some people enforce it for the sake of having comments in place, which would most of the time describe the "what" and the "how" of the code, rather than the "why", which in my opinion, where most of the value lies. In Java, the usual offenders would be the getter and setters in POJOs, like: * Returns the name * @return the name */ public String getName();
      - flatline3 14y ago
        Comments like that exist simply to appease documentation tools that can't derive those comments automatically. The net gain is that you get nice API documentation. The downside is that you have a verbose and obvious comment in the source.
      - slurgfest 14y ago
        Aren't such comments usually autogenerated by the IDE or such tools?
    - ucee054 14y ago
      The problem is not when programmer (A) writes the code and the comments correctly. Nor when jackass(B) updates the code and not the comments, making them misleadingly worse than no comments at all. But when the code now has to be maintained by programmer (C). This means you.
    - wanderr 14y ago
      The only thing worse than uncommented code, is wrongly-commented code. In my experience, code is almost always wrongly-commented, either because the programmer wrote the comment wrong in the first place, or because they wrote the code wrong, or because the code was later updated to do something different, and the comment was not updated to reflect the changes. In my experience, especially in an old codebase, it's extremely rare to find a piece of code that is both thoroughly and accurately commented. Given that reality, I would rather forego the comments for readable code. Readable code tells me what is going on, and doesn't lie!
    - einhverfr 14y ago
      In my considered experience, those who are most hostile to unnecessary comments tend to put the most comments in their code. It isn't an argument against code comments, just being very picky about what is a useful comment collaboration-wise.
  - sunwooz 14y ago
    Maybe he's saying, if your code is simple and elegant enough you won't need to comment.
    - flatline3 14y ago
      This is a fable bad programmers tell to themselves to justify their intellectual laziness. No real world code is simple and elegant enough that you don't need to think through the complex invariants of the code, consider would be relevant to future maintainers, and then write it down.
      - rimantas 14y ago
        > This is a fable bad programmers tell to themselves to > justify their intellectual laziness. No, actually commenting is easier solution for the lazy ones. Too bad they are to lazy to update the comments when something changes. > No real world code is simple and elegant enough that you don't > need to think through the complex invariants of the code Oh, please…
        flatline3 14y ago
        >> No real world code is simple and elegant enough that you don't >> need to think through the complex invariants of the code > Oh, please... sendDataWithTimeout(user_t *user, data_t *data, time_t timeout); What happens if delay is 0? Can user be NULL? What happens if it is NULL? How large can 'data' be? Is there a limit? Will the send be chunked into multiple dispatches if 'data' is too large? Is that opaque to the caller? Does it matter to the caller? If none of those questions are answered, the caller must delve into the sendDataWithTimeout() implementation to figure out the answers, and it is impossible to modify sendDataWithTimeout() without possibly breaking assumptions callers make based on what they've assumed from implementation of sendDataWithTimeout(). This applies equally well to blocks of code within a function that accept input and provide output. It helps to be able to reason about them as atomic units, without necessarily paying the code/maintenance cost of hoisting them into independent functions.
  - anusinha 14y ago
    A bad comment can waste a lot more time than the absence of a comment or a useless one (like x += n; //add n to x).
    - timo614 14y ago
      I'd say build your code such that you don't need to comment but comment wherever there is some unclear reason for why something is done. Instead of x+= n; running_total += total; But comments are helpful for understanding the reasoning behind why something was done. For example: $.resize.delay = 16; Was placed in one file of some code I collaborate on with the comment "// this is probably a horrible idea" I had to ask the developer what exactly the code does (yeah I could have looked it up but since he said it was a horrible idea I wanted to know why). Turns out it just configures the jquery resize event to fire at about 60 frames per second. Having a comment like: // Configures jquery resize to fire the resize event approx 60 frames per second Would have made the code a bit easier to understand.
      - electrograv 14y ago
        > Having a comment like: '// Configures jquery resize to fire the resize event approx 60 frames per second' Would have made the code a bit easier to understand. I'd argue that the following line is a better solution in every way than adding a comment as you suggest: setResizeEventFireRate(60); //just pseudocode of course Self-commenting code is always better: less duplication, less maintenance, greater refactoring agility, and most of all, it encourages you to design a cleaner system in the first place. Granted, in real-world scenarios, there will always be many cases where you are forced to add comments, sometimes extensively (hand-optimized code, inherently complex systems, etc).If anything though, this only confirms how important it is to aim for self-documenting code. Real-world production code is rarely a pretty thing, and the fact that you have to start adding comments everywhere is a reflection of this. You'd be surprised how clean and elegant code becomes when your only goal is to make it as self-descriptive as possible.
        timo614 14y ago
  - le-manchester 14y ago
    >Don't become the old people you hate, always try to learn new things, no matter how alien. So following that: There's a good talk about Code Documentation: http://www.youtube.com/watch?v=tCw7CpRvYOE http://www.youtube.com/watch?v=tCw7CpRvYOE
  - FuzzyDunlop 14y ago
    I think it could be summarised as thus, in general terms: You should never need to write a comment to explain what you're doing. If you feel you have to, rewrite the code until it doesn't need explaining in a comment. # this method manipulates dimensions def method_x(a, b, c, d) # a is the width # b is the height # c is the depth # d is a list of options ... end That could obviously be re-written as: def manipulate_dimensions(width, height, depth, options) ... end However, it may very well be the case you have to explain why some code exists, or why it wasn't done another way: def post_to_awkward_api(data) # stupid.io doesn't accept HTTP Post params # so we have to use a comma separated string silly_string = data.join(',') .... end def bug_fix_workaround # see http://stackoverflow.com/relevant-question/... end Not that my examples are amazing. But there'll always be the case where another developer (or even yourself) is not privy to the thought process that conceived a particular block of code.
    - DannoHung 14y ago
      We could probably resolve this aspect of the argument by teaching novices that a perfect/great/accurate/otherwise-superlative name(s) is better than almost any comment.
      - le-manchester 14y ago
        Not at all because programming languages like Ruby parameter names don't tell the full story: if you have def find(name) what kind of type could be name? String "Steve"?? Symbol :Steve? Hash {:first => "Steve", :last => "Jobs"} ??
        aneisf 14y ago
        That just means that 'name' is a poor name for the parameter. Have 'first_name, last_name' or 'full_name' or 'names,' for example. In addition, I think it's a good practice to get into to try and validate parameters at the top of any method. If the values don't fit your use for them, raise an exception.
  - donall 14y ago
    There's a lot of back-and-forth in this discussion already and I feel like some people aren't understanding that it's not about _never_ commenting the code; it's about only commenting when it is absolutely necessary (which is actually quite rare if you're writing clean, simple code (which is, itself, quite rare!)). I think that everybody should be required to read the chapter about commenting in "Clean Code" before contributing to this discussion. It's very java-centric and not perfect, but there is some really good insight. There is a pdf available here: http://www.tud.ttu.ee/material/kallik/JOOP/Clean_Code_-_A_Handbook_of_Agile_Software_Craftsmanship.pdf http://www.tud.ttu.ee/material/kallik/JOOP/Clean_Code_-_A_Ha... (if it really helps you, consider buying a copy and supporting the authors).
    - einhverfr 14y ago
      The key things are: 1) The code should speak for itself, and 2) You comment when you have something to say outside of what the code says. Chances are, ironically, if you stop using comments as a crutch, you will use them more often because they will start to be a useful tool.
- overgryphon 14y ago
  Don't hate the old people. They have a lot to teach.
  - tokenizer 14y ago
    You're right. I guess I meant the aspect of fear one has of new things as they get older. I hate that personality trait. It is more prominent in older people.
    - overgryphon 14y ago
      I don't think a lot of older people are afraid of new things. Instead they are more skeptical, because they've seen it before and it isn't as new as you'd like it to be.
- clwoodson 14y ago
  What others have said. Good code is self commenting. I prefer to see comments reserved for instances where its not clearly obvious why a piece of code exists (hacky workarounds, etc...)
norswap 14y ago
Work on unimportant problems. http://www.yosefk.com/blog/work-on-unimportant-problems.html http://www.yosefk.com/blog/work-on-unimportant-problems.html
recycleme 14y ago
Communicate often. Have a beer with a fellow programmer. Don't be afraid to break code.
- sukuriant 14y ago
  > Don't be afraid to break code. Just not in production :)
  - bbwharris 14y ago
    There's no better way to learn.
  - codegeek 14y ago
    Problem is that code always breaks in production. What we should strive for is not to cause a critical break that creates massive loss for the company. But code has and will break in production.
  - tene 14y ago
    Even better is to have an automated immune system that detects production issues and rolls back. We push to production dozens of times a day with dozens of engineers committing, and with that environment, problems will eventually slip through your local tests and buildbot. Bugs happen; it's far better to focus on robustly dealing with problems than it is to build layers of bureaucracy and process in an attempt to pretend that you can avoid all errors. At my current company, dozens of engineers are pushing to production dozens of times a day. We have an extensive test suite that runs on every commit before code can be pushed to production, but there's always something that slips through, which is why we also have an automated cluster immune system that can automate a rollback whenever any metrics go bad during or after a push. Bugs happen; life is better if you expect it and plan for it. My philosophy is, break production, and keep breaking it until you're damn good at dealing with production failures. Don't let fear of breaking production slow you down.
3am_hackernews 14y ago
It is written so beautifully that the "code" part of these thoughts can be substituted for many other things: design, engineering, life etc.
jawr 14y ago
>Always back up before tidying up. I liked this piece of advice, it's a lesson we all hate to learn.
- arscan 14y ago
  Happened to me last night -- I wish I read this yesterday. Who am I kidding... I prefer to learn these lessons the hard way :)
  - Ralith 14y ago
    Don't you use version control?
    - bestes 14y ago
      I read it as s/backup/commit
    - evincarofautumn 14y ago
      To be fair, version control and backups should be separate things.
      - jeremyjh 14y ago
        Right, because your backup is a VERSION of the code that you want to keep around, in case you need it right? Some version control tools don't let you create local, private versions. That is too bad. That doesn't mean that doing so is not a version control concern.
      - georgemcbay 14y ago
        IMO version control, file versioning and backups should all be separate things and ideally all available. Even when using a version control system that allows for robust local branches, sometimes it is nice to be able to revert a specific file's state to a known recent version that you never bothered to commit. Sometimes editor undo is sufficient for this, sometimes not. Dropbox and Google Drive have both saved me some time in this area (like 15-30 minutes, not days, but even that is appreciated) recently.
frou_dh 14y ago
Something in one of Zed Shaw's old talks stuck with me. Roughly: "Don't go with the flow of the industry. Try [unconventional] things because there's something beneath [software] that we haven't figured out yet." I suppose there's two personal disclaimers: - I'm not that interested in the business aspect of software. - The answer to what the magic beneath is may elude me due to it simply being "math, stupid".
- toomuchcoffee 14y ago
  ...due to it simply being "math, stupid". Care to elaborate?
cletus 14y ago
This is a great list. For one thing it's terse. > If you think you're as good as you're ever going to be - you're probably right. I completely agree with this. > If you think you're as good as you're ever going to be - you're probably right. The point being that motivation to improve and the belief that you can tend to be sufficient for growth. Absence of either tends to lead to stagnation. > Always back up before tidying up. One thing I love about IntelliJ is the Local History feature. It remembers you changes (going back days) to each file so rolling back isn't that hard. It's a bit like auto-save vs manual save in games. The great thing about it is you don't need to think about committing. It just does it automatically. What I'll add is: Programming languages, tools, etc are a means to an end not an end in and of themselves. What you produce matters. Showboating is counterproductive. I'm thinking of people who think that ASI (automatic semicolon insertion) and similar kind of mental masturbation tricks are a good idea when I say this.
podperson 14y ago
I liked "err vicariously" ;-) It's good to learn from your own mistakes, and even better to learn from someone else's.
- lobo_tuerto 14y ago
  Yeah, but sometimes "vicariously" doesn't cut it, you have to "do the work," you have to grind it out. http://raganwald.posterous.com/what-ive-learned-about-learning http://raganwald.posterous.com/what-ive-learned-about-learni...
  - podperson 14y ago
    Hey, it's a pithy one-liner (two-worder) -- and like any such chestnut is going to be wrong a lot of the time. Even so, learning from someone else's mistakes is "cheaper" than making mistakes yourself. The further you can get by avoiding mistakes others have made so you can get to your own personal mistakes, the better. I'd say "err vicariously" gets better the more you think about it, rather than needing to be nitpicked.
  - anthonyb 14y ago
    It's a maxim. It's supposed to guide your behaviour, not be taken 100% literally.
- worldsayshi 14y ago
  Yea. A good workplace is one in which calling "that one is my fault" is a natural part of your work flow and doesn't cost you points (unless you become to frequent).
alanmackenzie 14y ago
I would add: Don't release on a Friday.
- gacba 14y ago
  Sadly, the company I work for ONLY releases on Friday nights because the business closes out at 5pm. sigh
joe_bloggs 14y ago
"Err vicariously" Loved that. Subtle, yet deep!
twakefield 14y ago
> There's always plenty of room for improvement - in your code, in your abilities, in you. I just saw an amazing movie about a man that embodies this philosophy: "Jiro Dreams of Sushi"[1]. This man's dedication to further mastering his craft is unparalleled. Even though he is widely regarded as the best Sushi chef in the world, he is still singularly focused on becoming better every day. I highly recommend watching - it's very inspiring. [1] http://en.wikipedia.org/wiki/Jiro_Dreams_of_Sushi http://en.wikipedia.org/wiki/Jiro_Dreams_of_Sushi
joe_the_user 14y ago
Don't be an asshole Agreed but on the page, it looks a bit of out of place with the other points. My mind fills in the details as "don't act like you are the programmer who's a hundred times more productive than the others, even if it seems like you are". But that's a big question. Apple Computer arguably expects its programmers to all be the x100 producers and was managed by someone who it more or less was admitted to be an asshole (a genius, inspiration, unique asshole but still an asshole). So it think the greatness and asshole-dom question is not settled for people even if I would embrace it.
jebblue 14y ago
That was a short, concise, pragmatic, wise and rockin article.
einhverfr 14y ago
The bit about there always being room for growth was driven home for me yesterday as I was looking through how to build an object model in PostgreSQL using object-relational features. I went through the features one by one and discovered that I had only scratched the surface of that aspect of PostgreSQL. I suddenly understood how to rethink what I was doing in terms of design patterns in order to build object interfaces in the db for the relational underpinnings.

235 points by earnubs 14y ago

Be yourself. Code for fun. There's hundreds of ways to write the same thing, don't be a dick about your way, but stand up for good practices. Respect those who accomplish great things, because it was a lot of work, even if they say it was a weekend practice, they took a lot of time to get to that point. If you code correctly, one line changes are possible. Learn to desire success more than you fear failure. (I like this one) Don't become the old people you hate, always try to learn new things, no matter how alien. Who cares if you're coding on production live? Right? Right? Comments are for the weak, tracing and prototyping code is not. Mistakes are inevitable *It's hard being the smartest person in the room sometimes, wear it with humility rather than pride. My version of the list. This was fun!

nickolai 14y ago
>Comments are for the weak, Care to elaborate on this ? Commenting code is bad ? Or did I miss the irony ?
- recycleme 14y ago
  I've met a few senior level programmers who frown on detailed commenting (or commenting at all). I cannot wrap my head around this since I consider it best practice to comment. A reason given to me was that "it takes up too much time to comment and when you make a code change you need to make a change in the comments as well." To that I say, so what! I would like the future me (or the future programmer) to have full knowledge on what's going on in the code.
  - wreckimnaked 14y ago
    There's some debate on this: http://queue.acm.org/detail.cfm?id=1053354 http://queue.acm.org/detail.cfm?id=1053354
  - creativename 14y ago
    I feel like there are some people who go overboard on the formalities of commenting (specific format, etc.), but in general I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does". I even find that when I write comments to explain what a specific method is intended for, it helps me avoid violating the single-responsibility principle. If I clearly spell out what I'm trying to accomplish, it helps keep me focused. To those who say that the code should be elegant enough to be read on its own, there are some cases where the business logic involved is really what needs to be explained. At the same time, what is elegant and concise for you may appear obfuscated and confusing for someone else. You may argue that they should know all the techniques that you know, but that's just the reality of working with others sometimes.
    - lawn 14y ago
      > I can't think of one instance where I've thought "man, I wish I (or someone else) hadn't spent time explaining what this does". There are good uses of comments, but there are also bad ones. From Coding Horror [1] an example: '************************************************* ' Name: CopyString ' ' Purpose: This routine copies a string from the source ' string (source) to the target string (target). ' ' Algorithm: It gets the length of "source" and then copies each ' character, one at a time, into "target". It uses ' the loop index as an array index into both "source" ' and "target" and increments the loop/array index ' after each character is copied. ' ' Inputs: input The string to be copied ' ' Outputs: output The string to receive the copy of "input" ' ' Interface Assumptions: None ' ' Modification History: None ' ' Author: Dwight K. Coder ' Date Created: 10/1/04 ' Phone: (555) 222-2255 ' SSN: 111-22-3333 ' Eye Color: Green ' Maiden Name: None ' Blood Type: AB- ' Mother's Maiden Name: None ' Favorite Car: Pontiac Aztek ' Personalized License Plate: "Tek-ie" '************************************************* Now imagine something like this exists for every function and you're reading the source code... Annoying. Others are less extreme of course, but repeating the code in comments is bad and even harmful if you forget to update the comment as well as the code. DRY is a good principle to have. Of course "all comments are bad" is simply wrong, comments are essential to explain decisions or non-obvious snippets or gotchas.
  - arethuza 14y ago
    I tend to get a bit upset if code has comments that basically just describe what code is doing rather than why. Stuff along the lines of: // Increment the total total++; // Execute our SQL query var result = query.execute(); Seems to happen a lot with developers who use comments to "sketch out" code (not a bad thing) and then leave the comments in place when the actual code is written.
    - flatline3 14y ago
      I prefer code where I can skim the comments and see the major plot points, at a glance.
      - dllthomas 14y ago
        If you need to skim the comments to see how a function is doing what it's doing, the function is too long.
        flatline3 14y ago
        When it can take 3-4 statements to perform a single logical operation, there is still value in summarizing each block with a comment, even if the function isn't "too long".
        gnaritas 14y ago
        That's what function names are for. Comments don't need to summarize. A useful comments says why code is this way, it doesn't summarize or repeat code.
        flatline3 14y ago
        > That's what function names are for. A single function for every 3-4 line operation would result in incredibly disjointed code, and would require more explicit documentation of invariants because that function can now be called elsewhere (at least inside of the given translation unit). > A useful comments says why code is this way, it doesn't summarize or repeat code. That's nonsensical. Why wouldn't you want to abstract the complex?
  - flatline3 14y ago
    > I've met a few senior level programmers who frown on detailed commenting (or commenting at all). If they express those views, I wouldn't call them senior. Commenting is necessary to express invariants, and to summarize complexity that would otherwise require each reader of the code to understand the code itself in depth. Those are actually closely related things. Very few languages are capable of succinctly expressing sufficiently detailed invariants. Some are better than others -- maybe they support Maybe monads instead instead of possibly-NULLs. However, it's rarely possible to express -- purely in code -- what the code is supposed to do, what the input is supposed to be, and what the output is supposed to be. Failing to express those things means that any future reader/maintainer will be forced to trace your code, in its entirety, to reverse-engineer how it is probably supposed to work. In many cases said maintainer can never know for sure without tracing your code and ALL code that calls your code -- otherwise, any change to that code could break undocumented behavior that other code relies upon. Anyone who advocates against comments is justifying laziness, and they're wrong. The only supportable argument for not commenting is if a language is sufficiently powerful and succinct enough to express all the invariants normally expressed through comments, as well as being readable enough to permit a future maintainer to understand the design of the code without requiring them to spend an undue amount of time studying its inner mechanics. I'm not aware of such a programming language.
    - Ralith 14y ago
      Dependently typed programming languages can do the "express all the invariants" bit. Readability is an open question, though.
    - rimantas 14y ago
      “Don’t comment bad code—rewrite it.” —Brian W. Kernighan and P. J. Plaugher Is that senior enough for you? > Anyone who advocates against comments is justifying > laziness, and they're wrong No, they are actually advocating to put more effort in thinking about stuff: how you name your functions/methods/whatever, how do you name your arguments/parameters, how do you write the code itself. To anyone interested I recommend to get a copy of "Clean Code" and read the relevant chapter. IIRC "Code Complete" mostly agrees.
  - julsonl 14y ago
    The issue I have with commenting is some people enforce it for the sake of having comments in place, which would most of the time describe the "what" and the "how" of the code, rather than the "why", which in my opinion, where most of the value lies. In Java, the usual offenders would be the getter and setters in POJOs, like: * Returns the name * @return the name */ public String getName();
    - flatline3 14y ago
      Comments like that exist simply to appease documentation tools that can't derive those comments automatically. The net gain is that you get nice API documentation. The downside is that you have a verbose and obvious comment in the source.
    - slurgfest 14y ago
      Aren't such comments usually autogenerated by the IDE or such tools?
  - ucee054 14y ago
    The problem is not when programmer (A) writes the code and the comments correctly. Nor when jackass(B) updates the code and not the comments, making them misleadingly worse than no comments at all. But when the code now has to be maintained by programmer (C). This means you.
  - wanderr 14y ago
    The only thing worse than uncommented code, is wrongly-commented code. In my experience, code is almost always wrongly-commented, either because the programmer wrote the comment wrong in the first place, or because they wrote the code wrong, or because the code was later updated to do something different, and the comment was not updated to reflect the changes. In my experience, especially in an old codebase, it's extremely rare to find a piece of code that is both thoroughly and accurately commented. Given that reality, I would rather forego the comments for readable code. Readable code tells me what is going on, and doesn't lie!
  - einhverfr 14y ago
    In my considered experience, those who are most hostile to unnecessary comments tend to put the most comments in their code. It isn't an argument against code comments, just being very picky about what is a useful comment collaboration-wise.
- sunwooz 14y ago
  Maybe he's saying, if your code is simple and elegant enough you won't need to comment.
  - flatline3 14y ago
    This is a fable bad programmers tell to themselves to justify their intellectual laziness. No real world code is simple and elegant enough that you don't need to think through the complex invariants of the code, consider would be relevant to future maintainers, and then write it down.
    - rimantas 14y ago
      > This is a fable bad programmers tell to themselves to > justify their intellectual laziness. No, actually commenting is easier solution for the lazy ones. Too bad they are to lazy to update the comments when something changes. > No real world code is simple and elegant enough that you don't > need to think through the complex invariants of the code Oh, please…
      - flatline3 14y ago
        >> No real world code is simple and elegant enough that you don't >> need to think through the complex invariants of the code > Oh, please... sendDataWithTimeout(user_t *user, data_t *data, time_t timeout); What happens if delay is 0? Can user be NULL? What happens if it is NULL? How large can 'data' be? Is there a limit? Will the send be chunked into multiple dispatches if 'data' is too large? Is that opaque to the caller? Does it matter to the caller? If none of those questions are answered, the caller must delve into the sendDataWithTimeout() implementation to figure out the answers, and it is impossible to modify sendDataWithTimeout() without possibly breaking assumptions callers make based on what they've assumed from implementation of sendDataWithTimeout(). This applies equally well to blocks of code within a function that accept input and provide output. It helps to be able to reason about them as atomic units, without necessarily paying the code/maintenance cost of hoisting them into independent functions.
- anusinha 14y ago
  A bad comment can waste a lot more time than the absence of a comment or a useless one (like x += n; //add n to x).
  - timo614 14y ago
    I'd say build your code such that you don't need to comment but comment wherever there is some unclear reason for why something is done. Instead of x+= n; running_total += total; But comments are helpful for understanding the reasoning behind why something was done. For example: $.resize.delay = 16; Was placed in one file of some code I collaborate on with the comment "// this is probably a horrible idea" I had to ask the developer what exactly the code does (yeah I could have looked it up but since he said it was a horrible idea I wanted to know why). Turns out it just configures the jquery resize event to fire at about 60 frames per second. Having a comment like: // Configures jquery resize to fire the resize event approx 60 frames per second Would have made the code a bit easier to understand.
    - electrograv 14y ago
      > Having a comment like: '// Configures jquery resize to fire the resize event approx 60 frames per second' Would have made the code a bit easier to understand. I'd argue that the following line is a better solution in every way than adding a comment as you suggest: setResizeEventFireRate(60); //just pseudocode of course Self-commenting code is always better: less duplication, less maintenance, greater refactoring agility, and most of all, it encourages you to design a cleaner system in the first place. Granted, in real-world scenarios, there will always be many cases where you are forced to add comments, sometimes extensively (hand-optimized code, inherently complex systems, etc).If anything though, this only confirms how important it is to aim for self-documenting code. Real-world production code is rarely a pretty thing, and the fact that you have to start adding comments everywhere is a reflection of this. You'd be surprised how clean and elegant code becomes when your only goal is to make it as self-descriptive as possible.
      - timo614 14y ago
- le-manchester 14y ago
  >Don't become the old people you hate, always try to learn new things, no matter how alien. So following that: There's a good talk about Code Documentation: http://www.youtube.com/watch?v=tCw7CpRvYOE http://www.youtube.com/watch?v=tCw7CpRvYOE
- FuzzyDunlop 14y ago
  I think it could be summarised as thus, in general terms: You should never need to write a comment to explain what you're doing. If you feel you have to, rewrite the code until it doesn't need explaining in a comment. # this method manipulates dimensions def method_x(a, b, c, d) # a is the width # b is the height # c is the depth # d is a list of options ... end That could obviously be re-written as: def manipulate_dimensions(width, height, depth, options) ... end However, it may very well be the case you have to explain why some code exists, or why it wasn't done another way: def post_to_awkward_api(data) # stupid.io doesn't accept HTTP Post params # so we have to use a comma separated string silly_string = data.join(',') .... end def bug_fix_workaround # see http://stackoverflow.com/relevant-question/... end Not that my examples are amazing. But there'll always be the case where another developer (or even yourself) is not privy to the thought process that conceived a particular block of code.
  - DannoHung 14y ago
    We could probably resolve this aspect of the argument by teaching novices that a perfect/great/accurate/otherwise-superlative name(s) is better than almost any comment.
    - le-manchester 14y ago
      Not at all because programming languages like Ruby parameter names don't tell the full story: if you have def find(name) what kind of type could be name? String "Steve"?? Symbol :Steve? Hash {:first => "Steve", :last => "Jobs"} ??
      - aneisf 14y ago
        That just means that 'name' is a poor name for the parameter. Have 'first_name, last_name' or 'full_name' or 'names,' for example. In addition, I think it's a good practice to get into to try and validate parameters at the top of any method. If the values don't fit your use for them, raise an exception.
- donall 14y ago
  There's a lot of back-and-forth in this discussion already and I feel like some people aren't understanding that it's not about _never_ commenting the code; it's about only commenting when it is absolutely necessary (which is actually quite rare if you're writing clean, simple code (which is, itself, quite rare!)). I think that everybody should be required to read the chapter about commenting in "Clean Code" before contributing to this discussion. It's very java-centric and not perfect, but there is some really good insight. There is a pdf available here: http://www.tud.ttu.ee/material/kallik/JOOP/Clean_Code_-_A_Handbook_of_Agile_Software_Craftsmanship.pdf http://www.tud.ttu.ee/material/kallik/JOOP/Clean_Code_-_A_Ha... (if it really helps you, consider buying a copy and supporting the authors).
  - einhverfr 14y ago
    The key things are: 1) The code should speak for itself, and 2) You comment when you have something to say outside of what the code says. Chances are, ironically, if you stop using comments as a crutch, you will use them more often because they will start to be a useful tool.
overgryphon 14y ago
Don't hate the old people. They have a lot to teach.
- tokenizer 14y ago
  You're right. I guess I meant the aspect of fear one has of new things as they get older. I hate that personality trait. It is more prominent in older people.
  - overgryphon 14y ago
    I don't think a lot of older people are afraid of new things. Instead they are more skeptical, because they've seen it before and it isn't as new as you'd like it to be.
clwoodson 14y ago
What others have said. Good code is self commenting. I prefer to see comments reserved for instances where its not clearly obvious why a piece of code exists (hacky workarounds, etc...)

norswap 14y ago

Work on unimportant problems. http://www.yosefk.com/blog/work-on-unimportant-problems.html http://www.yosefk.com/blog/work-on-unimportant-problems.html

recycleme 14y ago

Communicate often. Have a beer with a fellow programmer. Don't be afraid to break code.

sukuriant 14y ago
> Don't be afraid to break code. Just not in production :)
- bbwharris 14y ago
  There's no better way to learn.
- codegeek 14y ago
  Problem is that code always breaks in production. What we should strive for is not to cause a critical break that creates massive loss for the company. But code has and will break in production.
- tene 14y ago
  Even better is to have an automated immune system that detects production issues and rolls back. We push to production dozens of times a day with dozens of engineers committing, and with that environment, problems will eventually slip through your local tests and buildbot. Bugs happen; it's far better to focus on robustly dealing with problems than it is to build layers of bureaucracy and process in an attempt to pretend that you can avoid all errors. At my current company, dozens of engineers are pushing to production dozens of times a day. We have an extensive test suite that runs on every commit before code can be pushed to production, but there's always something that slips through, which is why we also have an automated cluster immune system that can automate a rollback whenever any metrics go bad during or after a push. Bugs happen; life is better if you expect it and plan for it. My philosophy is, break production, and keep breaking it until you're damn good at dealing with production failures. Don't let fear of breaking production slow you down.

3am_hackernews 14y ago

It is written so beautifully that the "code" part of these thoughts can be substituted for many other things: design, engineering, life etc.

jawr 14y ago

>Always back up before tidying up. I liked this piece of advice, it's a lesson we all hate to learn.

arscan 14y ago
Happened to me last night -- I wish I read this yesterday. Who am I kidding... I prefer to learn these lessons the hard way :)
- Ralith 14y ago
  Don't you use version control?
  - bestes 14y ago
    I read it as s/backup/commit
  - evincarofautumn 14y ago
    To be fair, version control and backups should be separate things.
    - jeremyjh 14y ago
      Right, because your backup is a VERSION of the code that you want to keep around, in case you need it right? Some version control tools don't let you create local, private versions. That is too bad. That doesn't mean that doing so is not a version control concern.
    - georgemcbay 14y ago
      IMO version control, file versioning and backups should all be separate things and ideally all available. Even when using a version control system that allows for robust local branches, sometimes it is nice to be able to revert a specific file's state to a known recent version that you never bothered to commit. Sometimes editor undo is sufficient for this, sometimes not. Dropbox and Google Drive have both saved me some time in this area (like 15-30 minutes, not days, but even that is appreciated) recently.

frou_dh 14y ago

Something in one of Zed Shaw's old talks stuck with me. Roughly: "Don't go with the flow of the industry. Try [unconventional] things because there's something beneath [software] that we haven't figured out yet." I suppose there's two personal disclaimers: - I'm not that interested in the business aspect of software. - The answer to what the magic beneath is may elude me due to it simply being "math, stupid".

toomuchcoffee 14y ago
...due to it simply being "math, stupid". Care to elaborate?

cletus 14y ago

This is a great list. For one thing it's terse. > If you think you're as good as you're ever going to be - you're probably right. I completely agree with this. > If you think you're as good as you're ever going to be - you're probably right. The point being that motivation to improve and the belief that you can tend to be sufficient for growth. Absence of either tends to lead to stagnation. > Always back up before tidying up. One thing I love about IntelliJ is the Local History feature. It remembers you changes (going back days) to each file so rolling back isn't that hard. It's a bit like auto-save vs manual save in games. The great thing about it is you don't need to think about committing. It just does it automatically. What I'll add is: Programming languages, tools, etc are a means to an end not an end in and of themselves. What you produce matters. Showboating is counterproductive. I'm thinking of people who think that ASI (automatic semicolon insertion) and similar kind of mental masturbation tricks are a good idea when I say this.

podperson 14y ago

I liked "err vicariously" ;-) It's good to learn from your own mistakes, and even better to learn from someone else's.

lobo_tuerto 14y ago
Yeah, but sometimes "vicariously" doesn't cut it, you have to "do the work," you have to grind it out. http://raganwald.posterous.com/what-ive-learned-about-learning http://raganwald.posterous.com/what-ive-learned-about-learni...
- podperson 14y ago
  Hey, it's a pithy one-liner (two-worder) -- and like any such chestnut is going to be wrong a lot of the time. Even so, learning from someone else's mistakes is "cheaper" than making mistakes yourself. The further you can get by avoiding mistakes others have made so you can get to your own personal mistakes, the better. I'd say "err vicariously" gets better the more you think about it, rather than needing to be nitpicked.
- anthonyb 14y ago
  It's a maxim. It's supposed to guide your behaviour, not be taken 100% literally.
worldsayshi 14y ago
Yea. A good workplace is one in which calling "that one is my fault" is a natural part of your work flow and doesn't cost you points (unless you become to frequent).

alanmackenzie 14y ago

I would add: Don't release on a Friday.

gacba 14y ago
Sadly, the company I work for ONLY releases on Friday nights because the business closes out at 5pm. sigh

joe_bloggs 14y ago

"Err vicariously" Loved that. Subtle, yet deep!

twakefield 14y ago

> There's always plenty of room for improvement - in your code, in your abilities, in you. I just saw an amazing movie about a man that embodies this philosophy: "Jiro Dreams of Sushi"[1]. This man's dedication to further mastering his craft is unparalleled. Even though he is widely regarded as the best Sushi chef in the world, he is still singularly focused on becoming better every day. I highly recommend watching - it's very inspiring. [1] http://en.wikipedia.org/wiki/Jiro_Dreams_of_Sushi http://en.wikipedia.org/wiki/Jiro_Dreams_of_Sushi

joe_the_user 14y ago

Don't be an asshole Agreed but on the page, it looks a bit of out of place with the other points. My mind fills in the details as "don't act like you are the programmer who's a hundred times more productive than the others, even if it seems like you are". But that's a big question. Apple Computer arguably expects its programmers to all be the x100 producers and was managed by someone who it more or less was admitted to be an asshole (a genius, inspiration, unique asshole but still an asshole). So it think the greatness and asshole-dom question is not settled for people even if I would embrace it.

jebblue 14y ago

That was a short, concise, pragmatic, wise and rockin article.

einhverfr 14y ago

The bit about there always being room for growth was driven home for me yesterday as I was looking through how to build an object model in PostgreSQL using object-relational features. I went through the features one by one and discovered that I had only scratched the surface of that aspect of PostgreSQL. I suddenly understood how to rethink what I was doing in terms of design patterns in order to build object interfaces in the db for the relational underpinnings.