Live data from Hacker News

The Most Important Code Isn't Code

zachholman.com

51–60 of 83 posts

Re: The Most Important Code Isn't Code

#51
I think thar the most valuable documentation are the commit comments for the version control system you use.

Especially if one uses the incremental iteration paradigm, the commit history together with the code diff IS the documentation of one's code in it's most fundamental way, that is when I changed something, why, what I was ( thinking that I was ) doing etc.

In case that one has to maintain existing code, of course, the whole history is not available but still, refactoring committed similarly documents the evolution of the code in a similar way.

Re: The Most Important Code Isn't Code

#52
post #10

The documentation example for the multiplex() function seems like massive overkill to me. The most informative part of the documentation comment is the line that starts with "Duplicate some text..." So why not just name the function duplicate_text() and be done with it? The arguments could be documented similarly, by naming them "text" and "num_duplications". I don't think I'd need an 11 line comment to tell me what…

Not to mention the fact that the word "multiplex" already has a meaning, and it has nothing to do with concatenating duplicates of a string. Unless the function name is intended to be parsed as "multiple 'X'".

Rather ironic that the function "multiplex" as "multiple x" is included in an article that says:

"If you don’t have an absolute clarity in the code you’re pushing, it rears its head by way of bugs, confused coworkers, and slow code."

That's the single most confusing function name I've seen in a while.

Re: The Most Important Code Isn't Code

#53
Most discussions about commenting necessarily revolve around how to comment functions/methods/classes, when to comment, how to write code that is so intuitive that it doesn't necessarily require commenting, etc. In my opinion, these discussions miss out a key documentation requirement: describing how everything fits together.

Let's assume the supposed best-case: every single method and class is commented using a language-specific documentation system (I'm thinking of EDoc for Erlang, Javadoc for Java, etc). Who cares? Congratulations: I now know how all your functions work. But what is the system architecture? How do object instances of the different classes hang together to support the functional specifications? What is the sequence of events for various successful and failed transactions?

I suppose what I'm complaining about is the rationale that code commenting can necessarily substitute a solid set of functional specification and design documents. Then again, noone here made this suggestion, so maybe I'm just whining into a black hole. The only open-source project that comes to mind when I think of an astoundingly high quality of documentation is SQLite in the form of "Inside SQLite (2007)" (O'Reilly); unfortunately it's not free.

Re: The Most Important Code Isn't Code

#54

Even better than documented code is code that's so clear it doesn't need explanation, with occasional comments explaining the complicated bits. The other case is API docs for libraries and frameworks meant for external consumption.

I absolutely agree. I don't comment all that much, but comment where it's impossible to get clarity -- or comment at a higher level to explain the rationale for the code. Commenting what code does -- is either 1) pointless or 2) indicative you should rewrite your explanation-requiring code in a more straightforward fashion.

I comment for one person and one person only: myself in 6 months or 2 years when I've forgotten everything about this code! Strangely enough, that kind of attitude results in comments that everyone finds useful.

Re: The Most Important Code Isn't Code

#55
post #42
post #29

Ok, I'll be the curmudgeon here. In recent software development efforts I have run, I have put for the rule that "All comments are bugs". Comments get separated from the code, make statements about obsolete activities, and often mislead the reader, and even sometimes the author. In place of comments, write code that is as self-explanatory as possible. I refer to Martin Fowler's "Refactoring" as a way of trying to inc…

I would change "All comments are bugs" to "All comments document bugs we have to work around." Otherwise, some maintenance programmer is going to wonder why, only for Solaris, I use poll() on a single file descriptor when I immediately call recvfrom(). With a comment, I can inform said maintenance programmer that under Solaris, the observed behavior is that recvfrom() is NOT a pthread cancellation point, but poll() i…

And this sounds more like the why kind of comment rather than the what, which approach I agree with. That is, you are commenting the pieces of code that a reader would say "er, the heck?" with explanation.

Re: The Most Important Code Isn't Code

#56
post #50
post #41

Earlier quoted context omitted.

I find your comment valuable and largely agree, but it spurred me to write out an objection I have to a common view (not necessarily yours). What helps is using longer method/function/attribute/variable names Sounds great, so why don't all good programmers do that? This is a deeper question than it seems. Over time, I've come to mostly prefer short names. The reason is that longer names add lexical noise to the code;…

What do you think of short methods?

A friend of mine who was a smalltalk programmer for 17 years told me that the median length of his methods over his career was four lines. I think that this is admirable and wish my code were more like that.

Re: The Most Important Code Isn't Code

#57
post #56
post #50

Earlier quoted context omitted.

What do you think of short methods?

A friend of mine who was a smalltalk programmer for 17 years told me that the median length of his methods over his career was four lines. I think that this is admirable and wish my code were more like that.

It seems that having many small methods trades one complexity for another. For methods that are only used once and sequentially, it seems to me that it's easier to follow if they are all inlined (by the programmer). If the methods can be reused elsewhere, it's a different matter.

On the other hand, methods are modules, giving syntactic and compiler-supported semantic separation - and you can do things like return early.

I can't tell which is better.

Some people claim that short is better, but it always comes across as a bit rabidly dogmatic, because... well... it's without evidence. There is so much of that in comp sci: design patterns, functional programming, editor and language choice. Most people giving opinions don't even mention what type of task that advice is relevant for, nor give their experience that supports their choice. (It's easy to argue for a choice - smart people unfortunately can argue convincingly for anything.)

I tend to use separate methods only if they are reusable (otherwise it's a waste of time making them reusable). I often think of better ways of doing things, so I don't like to invest too much in what I have now. I'm mostly writing prototype code for new kinds of products, not "production code", not for clients, and no one sees it but me. Much code I've seen that it made of many methods and classes looks horribly over-engineered to me, especially when the problem itself is actually very simple if you approach it in the right way.

I'd love to hear gruseom's opinion tho.

Re: The Most Important Code Isn't Code

#58
post #50
post #41

Earlier quoted context omitted.

I find your comment valuable and largely agree, but it spurred me to write out an objection I have to a common view (not necessarily yours). What helps is using longer method/function/attribute/variable names Sounds great, so why don't all good programmers do that? This is a deeper question than it seems. Over time, I've come to mostly prefer short names. The reason is that longer names add lexical noise to the code;…

What do you think of short methods?

For fun, I'm going to write my thoughts before reading what you said about it elsewhere in the thread.

What do you think of short methods?

I'm skeptical of them. I think it's a mistake to try to make functions short for the sake of making them short. It's a mistake because adding a new function also adds complexity (i.e. more code, plus opacity between the calling and called) - not a lot, but greater than zero - so introducing a function is not cost-free and its benefit needs to be greater than its cost. I found that once I started asking functions to justify themselves this way, I began creating fewer functions and the overall complexity of my code went down.

Factoring code into functions is one of the best tools we have, of course, but people commonly make the mistake of applying it mechanically. A function should exist when the program itself wants that concept, not because you had a block of code that was too big or some duplication and you wanted to rearrange the pieces. The way to address those symptoms is not by adding more code but by thinking until you see how you were looking at the problem wrongly. Then the new concepts, and finally the new functions, appear by themselves.

You only have so many conceptual cards to play and must play them sparingly if you don't want your program to succumb to runaway complexity. A good function is a logical construct that makes sense in the meaning of the program the way a good word makes sense and adds a unique meaning to a language, something you can't quite say as well any other way.

When all you're doing is shifting pieces around, you're missing the most important thing about functions, which is this conceptual payload. After you do that for a while, your program stops evolving as an expression of the problem being solved, because you've built it out of primitives that refer only to the internals of the program rather than to concepts drawn from the problem space.

Side note. I'm writing at such length here and in the GP because these questions are on my mind all the time. I've been working on a hard problem for over two years now in an utterly immersed way, the kind where you dream about it every night, where time itself begins to blur. Our approach has been to evolve the program many times until it converges on a solution. The only way to do this is if the program doesn't grow as you evolve it. How do you build a system such that you're constantly adding new information and behavior to it, and yet the overall code doesn't grow? We've had to figure this out just to stay alive.

One more thing about function length - Steve McConnell cites studies that suggest that short functions aren't easier to understand. IIRC the sweet spot was between 50 and 100 lines, depending of course on the language. I've posted references to this on HN before. One should be careful about believing these studies because the empirical literature on software development is so poor. But it's at least interesting that such experimental evidence as exists runs counter to the "OO short methods" school.

Re: The Most Important Code Isn't Code

#59
post #57
post #56

Earlier quoted context omitted.

A friend of mine who was a smalltalk programmer for 17 years told me that the median length of his methods over his career was four lines. I think that this is admirable and wish my code were more like that.

It seems that having many small methods trades one complexity for another. For methods that are only used once and sequentially, it seems to me that it's easier to follow if they are all inlined (by the programmer). If the methods can be reused elsewhere, it's a different matter. On the other hand, methods are modules, giving syntactic and compiler-supported semantic separation - and you can do things like return ear…

I wrote my thoughts up above, but will respond to this here. I agree, both about the short methods school and about programming dogmas in general.

I went through a couple years of working in the OO short method style. Recently an old client called me back to help modify some code I'd done for them in 2004, so I went down for an afternoon to help them out. I was really embarrassed. It was obvious to me that I had strung things together in endless chains of delegation (tiny classes and short methods) not because that was simple but because it, at the time, was my belief about programming. I got that belief from other programmers I admired.

The truth is that this is how most of us work all the time. I don't mean short methods; I mean picking a style based on our beliefs -- mostly for emotional reasons -- and then seeing the entire programming world through that filter. To be able to just see the problem is difficult when you're operating from one of these positions. Much (most?) of what we do in software development is add extrinsic complexity, which is bad when the problems themselves are hard to begin with.

My experience is that your moment of "the problem itself is actually very simple if you approach it in the right way" does eventually come, if you make getting there a high priority. But it's challenging. Most of the time we don't even know what our assumptions and beliefs are, let alone have the flexibility to adapt them to the problem. It's usually the other way around: we adapt the problem to our beliefs because they determine how we even see the problem in the first place.

Re: The Most Important Code Isn't Code

#60
post #56
post #50

Earlier quoted context omitted.

What do you think of short methods?

A friend of mine who was a smalltalk programmer for 17 years told me that the median length of his methods over his career was four lines. I think that this is admirable and wish my code were more like that.

Hell, this reminds me of another thing I want to say. The word that leaps out here is "smalltalk". The short-method school of OO came from the Smalltalk world. It has since been extrapolated to other languages. I am skeptical of this extrapolation. It's fashionable to say language choice doesn't matter that much, but I think language choice has a powerful effect in conditioning how one thinks about one's program. Different languages give rise to different ideas, and ultimately very different programs. It wouldn't surprise me if the short-method style makes good sense in Smalltalk environments for reasons that don't naively extrapolate to other languages. But that's just a guess.

By the way, the reason the above language effect doesn't get discussed is that when we compare languages we're almost always talking about already-existing code (look at how you can write X in Haskell or whatever). This leaves out the most important factor, which is how the language affects the creation of X in the first place.

Post reply on HN