I'm curious what people think of my commenting style: http://github.com/akkartik/wart
You wrote a lisp? A unit tested lisp? Damn. Your commenting style seems good, it makes the code pretty readable. At least to me.
I opened 7 or 8 files at random, and saw a few (very few) one-liner comments, which meant very little to me. Then I opened main and saw you'd put an essay on Lisp at the top. So overall, and only because you asked - I'd call your commenting style "non-utilitarian" - no offense intended :-)
:) Aww, my goal is extremely utilitarian: to explain lisp to non-lispers. Many of the early files have long comments because readers need the most support early on when they're orienting themselves around a new codebase. By the end, you get a feel for how things work and the code gets more self-documenting. If the goal is to convey intent, surely intent can't be uniformly distributed throughout a codebase. It takes a lot more intent to start; once the fundamentals are in place the rest might even get built on autopilot. Beyond comments I've also been exploring other mechanisms for keeping code readable. I thought hard about file system organization: making it apparent where newcomers should start, and keeping files easy to move around and rename. I spend a lot of time coming up with names, and minimizing the number of names I use, because the vocabulary of a codebase needs to fit in a person's head far more than lines of code. And I write tests. Having lots of unit tests has an unexpected benefit for readability in the small. Don't understand why this line needs to be so? Try changing it or deleting it, run all tests. Something failed? Ah, it explains a design subtlety I'd forgotten about. Nothing failed? Sweet, dead code. Good names for tests are way more valuable than for functions because of this trick, but sadly most codebases don't have nearly the coverage necessary to make it tick. In general I'm far more cavalier towards my code than towards my tests. Take away my code if you want, but leave me my tests. That's where all the reproducible value is. A lot of my goal is to convey global intent. Often, discussion of one part includes interactions with other parts. What else? Oh yes, I'm not just writing comments in code files, I also have random files with just prose. And I love this quote for conveying the goal of design: If I look at any large part in overview, I can see what is going on -- I don't need to know all the details to get it. Every level of detail is as locally coherent and as well thought-out as any other level. -- Richard Gabriel, The Quality Without A Name
(http://dreamsongs.com/Files/PatternsOfSoftware.pdf, page 42)
I actually tend to be extremely anti-comments, so it was a little eye-opening to go back and notice how much prose I've written on this project. In the end, the goal is a good design, and there are no hard and fast rules. Just do what it takes.If I look at any small part of it, I can see what is going on -- I don't need to refer to other parts to understand what something is doing.
Well, turnabout is fair play, so if you'd like to critique my commenting style, there's some here :
http://hubski.com/pub?id=67105
(If you don't want to, I won't mind). Although I adapted that code from a library I found online, most of the commenting in there is mine.
I would argue that the need is project-dependent. Personally, I don't write them. However, if there are more than two of us working on Hubski, it's possible that I'll change that approach. Even so, familiarity with the code is what matters most when you are going to change it, and comments could give a false sense of familiarity, or could be misread. I previously programmed in Fortran with a professor that didn't comment. The code was terse, dense, and was expressing models of phase-transitions. Still, comments would have pretty much been a waste of time in that project. When I could read the code, it meant that I could meaningfully contribute. That said, I've never programmed in a large group. I suppose that if I did, I might comment. But, I don't use my phone's calendar because I forget to enter things. Commenting would take some serious discipline for me. I wonder what akkartik thinks of my commit comments. :)
We've had some teething pains, but that's mostly because of moving servers and foisting git on you :) In the abstract I care about commit messages far more than I care about comments, because I believe comments are more useful with a timestamp. But it's still been low down my priorities given all the different technical debt we have to pay off. Since I'm already familiar with arc, comments seem mostly irrelevant right now. They'll become important at some point if we need to involve others. Maybe with the API? :) --- Talking about comments in isolation as a measure of codebase quality is like talking about height in isolation as a measure of mate quality. I think that's what your criticisms boil down to, and they're perfectly valid. If the goal is to get newcomers to a place where they can meaningfully contribute, that drives everything. Well-functioning small teams rely on interactive discussion to orient newcomers. Since it's not clear that comments would ever replace in-person interactions, the default position tends to be that they're unnecessary/luxuries/evil, and that's reasonable. In large teams, in-person interactions gradually get expensive, and that causes greater reliance on comments and other mechanisms. I started out anti-comments, but have reluctantly come around to believing that there's nothing to replace them in certain situations. My current goal is to make the codebase intelligible to others even when I'm not around to explain it. That seems hard enough that I can't afford to be too ideological. Bottomline: comments are sometimes useful, but there's too much dogmatic thinking on both sides battling over them. Attend to the big picture.
It's up in the air. Currently, forwardslash is working on a mobile-friendly version. However, I am seriously reticent to follow an API cycle that has been repeated so many times over the web. That is, an API is released, the site benefits from the creativity and energy of the programming contingent of the community, and then the site moves into a place where the API runs counter to the road map. It's something that we've been discussing.
Personally, at the very least, I think programmers should document their code in some way. This can be anything from a write-up of its overall design if it's going to be left to another programmer, or python / Java docstrings so you can take advantage of the many IDEs/IDLEs that can show you that information on the fly. Comments, at the bare minimum in this case might mean noting places where you are doing something out of the ordinary (Portability provisions, dealing with library quirks, etc) More than that? You'll probably benefit in the long run, but many projects are under time constraints or aren't meant to last.
Any yet they do. There is an awk abomination I wrote for converting IRIS GL programs to OpenGL 1.mumble in the mid-2000s to aid friend in the chemistry department in migrating some software off of Irix on EOL'd SGI boxen. It was supposed to be a one-off. It is still in use, because they didn't want to bother learning a new API. They just added make targets to run the conversion. I don't know, but strongly suspect, that there are poor abused graduate students who would have appreciated a few comments in there.many projects are under time constraints or aren't meant to last.
Commenting is absolutely necessary. I only do a marginal amount of "coding" in VBA (due to Microsoft Excel), and Matlab. Even in those I would never be able to fully understand another persons function without commenting. I can't even imagine what it must be like for actual programmers to try and understand code without thorough comments.
Every place I've ever worked has been completely and utterly devoid of comments and documentation. One day maybe I'll get lucky and work somewhere where code readability is a goal, but I'm not counting on it. Generally the only thing that matters is that the project gets done on time..and sometimes your superiors care if it works well. Generally, though, management couldn't give two shits about the fact that it's duct taped together and will be a nightmare to maintain 6 months down the road.
You don't write comments for others. You write them for yourself, 6 months or two years from now. They are still not to be trusted, but can sometimes save your ass anyway. FIXME comments are downright useful sometimes.
Good story - I've heard of CTSS, it had a big influence on the guys who created Multics, which eventually spawned Unix. I seriously doubt it's a lack of commenting that prevents interpretation - I imagine a lack of hardware or other supporting functionality (missing software) is the only thing that could deter a dedicated historian-hacker. Speaking of history - here is an oldie but a goodie from the Jargon file, "The Story of Mel" - it's an epic hacker saga from the early days.
Commenting definitely isn't the only thing preventing people from running the code, but it definitely contributes to preventing people from reading it. Say, if some historian wants to learn about what the coders were thinking and why they did what they did, even technical commentary could help quite a bit, I suppose. So remember, comment for posterity!
Personally I find the notion of reading code without first running it to be meaningless[1]. We're unable to make sense of that program not because somebody didn't put some squiggles at the ends of lines prefixed by the right header, but because no muchine can run them, so we can't play with making changes and seeing what happens. [1] Cue Dijkstra rolling over in his grave.
Yeah that's a goodie. Rereading, I was struck by this quote about the patent office: (http://opinionator.blogs.nytimes.com/2011/06/21/did-my-broth...)Today, people are filing patents, claiming that they just invented something which we had running back in the 1960s. How can that happen? Well, the patent office looks only at previous patents to see whether or not there is a prior claim. Of course, there are no patents from the 1960s, because they wouldn’t allow them. You were supposed to send the patent office not just a description, but a hardware implementation. Basically the notion of patenting something meant you carried to the office a model of the thing you were building, the thing that you had invented. And this just doesn’t work with software. So they had, for a long time, declared software as an unpatentable thing. Eventually, they decided that there is indeed intellectual property here, but it was quite a while later.
As a coder (and please all the other coders on here), what's your stance on the patent mess right now? To my mind (and I'm not a programmer, for what it's worth), I think that a computer program is a text, and therefore should be subject to copyright, but not patent rules. The whole idea of patenting, well, an idea, is absolutely silly, in my opinion. And, its ruining innovation in the tech sector (biology, too, for similar reasons).
Yeah I agree with that reasoning. In addition, there's a broader problem with patents that software is just one symptom of. I'm still uncertain whether it's affecting innovation, however. Perhaps the patent system was needed to encourage innovation in a different time. Now we pretty much as a society buy that innovation is good. Perhaps patents are a sort of vestigial organ for large swathes of the state space. Broken patents don't cause people to stop innovating. They just cause people to stop patenting true innovations, and to retreat to trade secrets. The only people still filing patents in the tech industry are the dinosaurs and the clueless noobs.