Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Every line of code is always documented

mislav.uniqpath.com

Post reply on HN
Print view View original

91–100 of 104 posts

Re: Every line of code is always documented

#91

Post by markm208 »

Dylan16807 wrote: post #75
markm208 wrote: post #51

I agree with the author that historical information about how a codebase has evolved is important. I would also argue that code comments are not always the best place for this historical information (if you don’t know about the deep past of a bit of code, then why would you want to see a code comment describing some change to it?). I suggest we take a step back and ask if modern version control is the best way to sto…

If I have to later see every dumb thing I let within ten feet of my IDE window while working, I'm going to set the computer on fire and code pen on paper for later transcription.

Ha ha... yes, it sounds painful but imagine you come across a function that you don't fully understand. You can highlight it and watch how that code evolved. The code will be animated very easily (compared to trying to reconstruct the history from some VCS). Most people will never watch (or care about) you writing code but sometimes it may be very useful.

Re: Every line of code is always documented

#92

Post by adamlett »

jpatte wrote: post #32
adamlett wrote: post #28

Earlier quoted context omitted.

Of course he is right. But he still completely missed the point of the article, which was not to defend writing or keeping code that is not self explaning. I mean, it's the goddamn premise of the article that you happen to stumple upon a piece of code that's less than perfect! The example in the article describes a situation in which you find a piece of code someone else wrote and you are unsure of what it does or wh…

The premise of the article is that you happen to stumble upon a messy piece of code and that the explanations related to it might be located into the source history. Yet the only reason why these explanations would actually be there is that someone would have enforced doing that as a rule. And the point of the counter-argument is that before enforcing this rule this same person should be enforcing a rule saying that…

That's like saying that a "counter-argument" to wearing a seatbelt is that drivers shouldn't be getting into accidents in the first place. Yes, it would be nice if all code was well-commented and well-factored with well-named functions, classes and variables, and we should all strive to make code like that. And if that never failed, then perhaps we wouldn't need any other best practices or rules to help us along.[1] But we all know the real world is not like that. We need all the help we can get. Having good practices for writing good code is not, I repeat not an argument against having good practices for commit comments. You make it out to be an either/or proposition. It's not.

Re: Every line of code is always documented

#93

Post by Roboprog »

darryl42 wrote: post #27
gizmogwai wrote: post #4

I wish my current coworkers wrote any comment in there commit message...

I wish management allowed comments. Commits are work item number and title or work item only. Comments in code are actively removed.

Fascinating: they care enough to consider such things, but they have made an insane decision.

Good luck there.

Re: Every line of code is always documented

#94

Post by geoka9 »

mistermann wrote: post #73
geoka9 wrote: post #41

Earlier quoted context omitted.

> This is probably not a popular view, but I don't really understand why comments are viewed by some people as a bad thing. Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty.

> Probably the same people think that well-written code does not need comments at all. That may be so, but well-written code is hard to come by. While this rock-star macho attitude is aplenty. Not only that, but I speculate that those holding such opinions are usually young, well above average programmers who therefore work exclusively on brand new projects - many of them have literally never experienced the nightmar…

Yes, it's easy (and fun) to write clever code that is unmaintanable. It's much harder to write code that is simple. To me, people who can do that day in, day out are true rock-stars of programming.

Re: Every line of code is always documented

#95

Post by Roboprog »

tshadwell wrote: post #61

Is this Javascript? Why is there no semicolon?

Despite advice to the contrary, Javascript is a line oriented language and you only need the semicolon if you intend to stack a second statement on the same line (kind of like colons in BASIC)

Yeah, I know that's blasphemy, but it's also true: Javascript works just fine WITHOUT all the extra semicolons. The semicolons are only needed in the minds of those who have been misled to believe that they are. One should learn what JS thinks are complete statements -- where to wrap longer statements without causing an error -- as Javascript WILL end statements without semicolons. Better to just never use semicolons in the first place.

And this is all off-topic...

Re: Every line of code is always documented

#96

Post by Roboprog »

Mostly a good article. I would put more emphasis on using history/annotate ("blame") for timeline and summary information, and using the inline comments for detail information.

Others have mentioned the "no comments" culture. To them I say: each file/class and each function/method/subroutine should have a summary comment, so I can know to skip over the irrelevant modules when I am looking for how to do something. I don't want 80 to 100 character identifiers (getMatrixResultButNotCornerCaseANorCornerCaseB or some such ridiculous name), but I do want a bit more summary than the name, contained within a statement of purpose comment.

Re: Every line of code is always documented

#97

Post by Roboprog »

salgernon wrote: post #60
hermannj314 wrote: post #44

Earlier quoted context omitted.

I concur. I've worked in enterprise. If your team relies on a centrally administered source control, then you can be in a world of pain if the central team decides to switch tools (and when this happens moving your revision history comments to the new system will never be considered important, if even possible). Keep important things in the code. That's my experience.

rcs -> sccs -> cvs -> svn -> git, with a trip through MPW Projector. Half the commit comments lately are "why the hell did git do this to me".

At least you got to skip going through such wonders as Source Safe, ClearCase, MKS Source Integrity or Serena Version Manager.

I'm not sure what MPW Projector is, but the rest are pretty mainstream.

It's amazing how many proprietary revision control systems there are, and how much worse they are than the free ones.

RCS clearly wasn't good enough for a team (distributed or not) or concurrent development, but CVS was good enough, with incremental improvements by SVN & Git.

The proprietary systems usually offer integration with a but tracker (mandatory ticket ID on check-in/commit) to lure the ignorant who don't know about commit triggers. Otherwise, they tend to be very slow, frequently time-out their licenses / login-sessions, and/or have a very deficient command line interface making it difficult to script a build system.

Re: Every line of code is always documented

#98

Post by akkartik »

dkuntz2 wrote: post #78
akkartik wrote: post #70

Earlier quoted context omitted.

Most interesting. I recently did some work on a new, version-control-inspired layout for programs, but from a different angle than you suggest: http://akkartik.name/post/wart-layers . I'd love to chat more about the details of what you're trying (email in profile).

Two questions: 1. How is that different than functionizing things? And, is it better? Especially because in wart it looks like your snippets can only be used once. 2. Does this bring you any advantages that well commented code doesn't? From my admittedly limited point of view (I haven't run it, just looked at your two examples) it looks like following the flow of control is a little more difficult, because it looks l…

The biggest limitation of functions is precisely what you point out: they create scopes. So you end up complecting (http://www.infoq.com/presentations/Simple-Made-Easy) what variables you need access to at a time with what variables you want to describe and explain at a time.

I don't think it's controversial that functions have limitations. For example, OO in many ways was an attempt to work around the limitations of functions. But what OO discovered, I think, was that any sort of modularity mechanism when baked into the language brings in its own constraints, which limit the situations where it can be used. The classic example is all the constraints on C prototypes that make any sort of refactoring of include files an NP-hard problem, dooming lots of codebases to never get the reorganization they need to free them from historical baggage. So I've gradually, grudgingly started to focus on more language-independent, tool-based approaches that can overlay an 'untyped' layer atop even the most rigid language.

"Because variables are accessible and manipulable in your snippets there isn't any containment like you get with functions."

My claim (http://akkartik.name/post/readable-bad) is that in seeking local properties like containment/encapsulation we deemphasize global understanding. Both are useful, certainly, but they're often in tension and our contemporary rhetoric ignores the tension. The pendulum has swung so much in favor of local rules for 'good style' that it's worth temporarily undoing some of that work to see what we're giving up, what the benefits of playing fast and loose with local structure might be.

"..following the flow of control is a little more difficult.."

Yeah that's a valid concern. I think literate programming failed to catch on partly because we need at times to see the entire flow of control in a function. Like when we're debugging. I have a vague vision that programmers of the future will work with the expository and 'tangled' views of a program side by side. (In addition to perhaps a view of the runtime execution of a single unit test: http://akkartik.name/post/tracing-tests.)

Your point about reusing snippets is also a good one. That's the benefit of naming fragments in literate programming, isn't it? I hadn't considered that; the examples I've seen never mention it. But emacs org-mode and http://leoeditor.com certainly seem to find reuse useful. Hmm. I haven't encountered the need for reusing snippets so far. That might change, and we can probably come up with some syntax to support it if so. I suspect, however, that our languages already have plenty of primitives for enabling reuse. We don't need any extra tool or meta-linguistic support.

---

Clicking through to your profile I ended up at http://essays.kuntz.co/you-re-probably-not-for-hackers, which suggests we have kindred sensibilities about these questions! (Compare http://akkartik.name/about)

Re: Every line of code is always documented

#99

Post by dkuntz2 »

akkartik wrote: post #98
dkuntz2 wrote: post #78

Earlier quoted context omitted.

Two questions: 1. How is that different than functionizing things? And, is it better? Especially because in wart it looks like your snippets can only be used once. 2. Does this bring you any advantages that well commented code doesn't? From my admittedly limited point of view (I haven't run it, just looked at your two examples) it looks like following the flow of control is a little more difficult, because it looks l…

The biggest limitation of functions is precisely what you point out: they create scopes. So you end up complecting ( http://www.infoq.com/presentations/Simple-Made-Easy ) what variables you need access to at a time with what variables you want to describe and explain at a time. I don't think it's controversial that functions have limitations. For example, OO in many ways was an attempt to work around the limitations…

I think the emphasis on containment and local understanding is good, especially considering that programs are getting huge (which is a separate problem, and what I think really needs to get fixed). With huge programs it's infeasible to fully comprehend the whole program, which means the only thing you can really do is hope that other programmers' functions work as advertised, and focus on perfecting your local domain.

The easiest way to alleviate this, in my opinion, is to focus on building smaller programs which focus on doing one thing well, and combining those together to create larger applications, with preferably a minimum of glue code. In my mind this leads to even more containment as each domain is now accessible only through the specified API.

This could lead to similar problems that you have with the deemphasis of global understanding, because it's still compartmentalizing things, and at each higher level the programmer is just trusting that the lower levels have implemented what they said they would, just like in a huge, single program.

The idea of being T-shaped specifically when it comes to the overall knowledge of the projects you work on seems to be the best way to work on those applications: have a general understanding of the whole project, and a really good understanding of your specific domain (and perhaps an intermediate understanding of those around yours).

Re: Every line of code is always documented

#100

Post by mislav »

jpatte wrote: post #77
gfodor wrote: post #54

Earlier quoted context omitted.

jesus christ http://lsolum.typepad.com/legal_theory_lexicon/2003/09/legal... this article is about recommendations of what to do ex post once a comment-less line of code has been committed in the past that you need to understand. arguments about ex ante things such as how it got there in the first place and how to prevent it from happening is completely orthogonal to the point of the article.

As rymohr indicated, the author of the code given as example is actually the author of the article himself: https://github.com/madrobby/zepto/commit/3d92f20966aa02dee82... Which means the OP genuinely thinks that commits like this one are good practice, and the purpose of the article is to show how to deal with it. Yet as it was argued above, commits like that should never happen in the first place.

And it didn't. This was the commit that actually happened: https://github.com/madrobby/zepto/commit/2ed0123eaddc023a857...

Notice the code comment. I took it out for the example in the blog post to illustrate how we would deal if there was never a code comment in the first place.

Post reply on HN