What prose do you write with your code?

A place to discuss the implementation and style of computer programs.

Moderators: phlip, Moderators General, Prelates

heatsink
Posts: 86
Joined: Fri Jun 30, 2006 8:58 am UTC

What prose do you write with your code?

Postby heatsink » Tue Jul 01, 2014 3:17 pm UTC

I recently read The Mythical Man-Month, a collection of essays about large software projects. It discussed some kinds of documentation that I haven't heard of before, such as a "project workbook" that collects all persistent prose associated with a project into one paper trail.

Besides comments (we either comment our code diligently, or pretend that we do), what kind of writing do you do along with programming? Are your commit logs longer than a sentence? Do you write up a design before you start coding?

User avatar
WarDaft
Posts: 1583
Joined: Thu Jul 30, 2009 3:16 pm UTC

Re: What prose do you write with your code?

Postby WarDaft » Tue Jul 01, 2014 4:27 pm UTC

I don't even write that many comments. I've had like, 17 commits in a row where the commit log is "."

Documentation would be the main exception, and I rarely have to do that.
All Shadow priest spells that deal Fire damage now appear green.
Big freaky cereal boxes of death.

User avatar
Lopsidation
Posts: 183
Joined: Tue Oct 27, 2009 11:29 pm UTC

Re: What prose do you write with your code?

Postby Lopsidation » Wed Jul 02, 2014 12:23 am UTC

When I'm working on a large project, I put TODO lists in the home directory and in incomplete code files. Besides comments, that's about it.

EvanED
Posts: 4330
Joined: Mon Aug 07, 2006 6:28 am UTC
Location: Madison, WI
Contact:

Re: What prose do you write with your code?

Postby EvanED » Wed Jul 02, 2014 3:37 am UTC

Stats across the last 235 commit log messages I have written (an arbitrarily-chosen number). These are number of words (as counted below):

min: 1
max: 392
median: 14
average: 31
20th percentile: 8
80th percentile: 41

A Python script that (with a couple tweaks) generated it; run on the output of svn log --xml:

Code: Select all

import xml.etree.ElementTree as ET
import re
r = ET.parse('logs.xml')
my_commits = [log for log in r.getroot()
              if log.find("author").text == "me"]
my_msgs = [log.find("msg").text for log in my_commits]

def exclude_line(line):
    line = line.lower()
    if not line:
        return True

    return False

def stats(msg):
    lines = msg.split("\n")
    lines = [line for line in lines
             if not exclude_line(line)]
    num_words = sum(len(list(w for w in line.split() if w)) for line in lines)
    num_bytes = sum(len(line) for line in lines)
    if num_words < 5:
        print lines
    return num_words

all_stats = sorted(stats(msg) for msg in my_msgs)
print all_stats

print "min:", min(all_stats)
print "max:", max(all_stats)
print "median:", all_stats[len(all_stats)/2]
print "average:", sum(all_stats)/len(all_stats)
print "20th percentile:", all_stats[len(all_stats)/5]
print "80th percentile:", all_stats[len(all_stats)*4/5]

The main twerk was a change to 'exclude_line' to exclude some bookkeeping stuff we have to track information such as who reviewed it.

My shortest commit message was "svn:ignores". (Actually, three of the eight commits with four or fewer words were adding svn:ignores.)
-----
More generally, a fair number of "how should we do this" emails go around, and we fairly often produce some descriptions of what we will be implementing before doing it. Those can involve some mathematics to show how things work. Affecting things perhaps is that the problems we are trying to solve are provably impossible to solve. :-) So we have discussions and brainstorming and stuff to try to figure out how to get a solution that works better than what we have currently.

tectonic
Posts: 5
Joined: Sat Jul 05, 2014 4:23 pm UTC

Re: What prose do you write with your code?

Postby tectonic » Sun Jul 06, 2014 11:26 pm UTC

I write very little prose with my code unless I think that the next person to encounter it will be surprised or confused, even after having read the unit tests.

(The Mythical Man-Month is an interesting and highly influential book, even if it feels a bit dated now.)

User avatar
ahammel
My Little Cabbage
Posts: 2135
Joined: Mon Jan 30, 2012 12:46 am UTC
Location: Vancouver BC
Contact:

Re: What prose do you write with your code?

Postby ahammel » Mon Jul 07, 2014 2:13 am UTC

I generally have at least a few words of documentation for each method, class, and module.

I'm also a big believer in working things out in paper first, but my handwriting is such that these documents are of no conceivable use to anybody but myself.
He/Him/His/Alex
God damn these electric sex pants!

User avatar
Quizatzhaderac
Posts: 1554
Joined: Sun Oct 19, 2008 5:28 pm UTC
Location: Space Florida

Re: What prose do you write with your code?

Postby Quizatzhaderac » Fri Oct 31, 2014 5:21 pm UTC

Heatsink, I don't know your background, so I'm sorry if this sounds insulting, but you do understand that many of the people working on large software projects aren't programmers right?

Non-programer documents that would contribute to the project workbook include:
  1. Financial justification for the project.
  2. Business requirements.
  3. Test plans, test results.
  4. Work schedules
  5. Requests, approvals, sign-offs, and thirty-one flavors of ass-covering.
  6. Meeting minutes.

I don't think actual comments in code or commit messages would be likely to end up in a project workbook.

Documents typically produced by programmers would be:
  1. Technical design document: How the developer intends to accomplish the task. Often ties specific changes to specific requirements. Common standard is enough information that another developer could perform the change. Servers as a high level alternative to version history to see what changed. Also sometimes work reassigned or a long period passes between a developer designing a change and coding it that they need a reminder.
  2. Unit, integration testing: Qualitative descriptions of what was tested and how. These are likely what the TPS reports in office space were.
  3. Requests to other IT personnel for changes under their jurisdictions.
  4. Deployment instructions
  5. Change documentation - let everyone know whats changing, when, how to prepare for it, how''ll they'll need to help, ect.
The thing about recursion problems is that they tend to contain other recursion problems.

User avatar
You, sir, name?
Posts: 6983
Joined: Sun Apr 22, 2007 10:07 am UTC
Location: Chako Paul City
Contact:

Re: What prose do you write with your code?

Postby You, sir, name? » Fri Oct 31, 2014 7:19 pm UTC

Very little, as documentation tends to go very stale very fast.

I strive for readable and easily maintainable code instead. I only do design before development if we're multiple people developing the same module, which is pretty rare. Most of my development is top-down, with unit tests documenting expected behavior and integration tests documenting module interaction.

I occasionally write documents or hold presentations to help new developers understand the code or the business logic, but I don't think that qualifies as documentation.
I edit my posts a lot and sometimes the words wrong order words appear in sentences get messed up.

Tyndmyr
Posts: 11233
Joined: Wed Jul 25, 2012 8:38 pm UTC

Re: What prose do you write with your code?

Postby Tyndmyr » Mon Dec 29, 2014 1:16 pm UTC

heatsink wrote:I recently read The Mythical Man-Month, a collection of essays about large software projects. It discussed some kinds of documentation that I haven't heard of before, such as a "project workbook" that collects all persistent prose associated with a project into one paper trail.

Besides comments (we either comment our code diligently, or pretend that we do), what kind of writing do you do along with programming? Are your commit logs longer than a sentence? Do you write up a design before you start coding?


It seriously depends on the projects. I have had some that have been documented gloriously. I've had others with just "//formatting and fixing happens here" before six pages of obscene code and no external documentation.

Depends what the project is for, who might need to work with it and why.

schapel
Posts: 244
Joined: Fri Jun 13, 2014 1:33 am UTC

Re: What prose do you write with your code?

Postby schapel » Thu Jan 01, 2015 11:52 pm UTC

I'm working on a project where I was brought in to modify an existing program. I didn't understand how the program worked, in the sense of what the overall plan or architecture of the program. It turned out that the program is using the GUI thread to schedule all tasks, and these tasks are real-time tasks that read sensor data and need to return a result based on that sensor data as soon as possible. Clearly, the architecture was seriously flawed.

The first thing we did was start with a new architecture, where the tasks are independent processes that communicate using message queues. The documentation I wrote described all the processes and messages of the system and how they interact to form the architecture of the system.

More generally, you want to write up a design document that describes the overall design of a system before you start programming, as long as the system is sufficiently complicated to warrant such documentation. The overall architecture is probably the most important documentation for programmers besides the code comments and instructions for how to build the program.

I would think that if it's designed for anyone else to rum you'd want a user guide also.

Tyndmyr
Posts: 11233
Joined: Wed Jul 25, 2012 8:38 pm UTC

Re: What prose do you write with your code?

Postby Tyndmyr » Fri Jan 02, 2015 4:03 pm UTC

My big worry there is that the design doc gets lost, becomes irrelevant as system changes get made, etc.

A good, up to date design doc is nice if you get one but...I've never actually received such. More probable is "this thing hasn't had anyone coding on it for a coupla years, before that, the last guy didn't update the documentation, and we have a bunch of poorly defined things we'd like it to do in addition to it's current stuff". This sounds a wee bit cynical, but it happens quite a lot in practice. A change here, a change there, and soon documentation is sketchy at best.

Comments at least tend to stick with the code. Granted, the best code is mostly self descriptive, and shouldn't need all that many comments save for high level stuff, but...maintence seems to always be an area that gets the short end of the stick. I think it's best to assume the same will likely be true of anything you write.

User avatar
roflwaffle
Posts: 360
Joined: Wed Jul 01, 2009 6:25 am UTC

Re: What prose do you write with your code?

Postby roflwaffle » Sat Jan 03, 2015 9:29 pm UTC

I'm new to coding, so I shoot for a code to comment ratio of ~3:1 to keep track of what I'm doing and why I'm doing it. I don't have a job as a developer, but I routinely look through code at work to try to figure out what's going on for customers. We mostly use comments to reference changes/TFS work items so we can move certain changes in and out quickly, and also have documentation that's directly ties code to requests from the business to reference later.

User avatar
Quizatzhaderac
Posts: 1554
Joined: Sun Oct 19, 2008 5:28 pm UTC
Location: Space Florida

Re: What prose do you write with your code?

Postby Quizatzhaderac » Mon Jan 05, 2015 10:09 pm UTC

That seems like a good strategy to start with. 3:1 seems a bit high for an experienced coder, but I'll be easier to drop obvious comments later than to realize you're omitting something.

Regarding referencing work items: if you need code comments (as opposed to check in comments and associated work items) to help track changes, your classes may be too large/coupled.
The thing about recursion problems is that they tend to contain other recursion problems.

User avatar
Xenomortis
Not actually a special flower.
Posts: 1421
Joined: Thu Oct 11, 2012 8:47 am UTC

Re: What prose do you write with your code?

Postby Xenomortis » Mon Jan 05, 2015 10:25 pm UTC

Sounds like you need a ticket system and source control.
Image

User avatar
Quizatzhaderac
Posts: 1554
Joined: Sun Oct 19, 2008 5:28 pm UTC
Location: Space Florida

Re: What prose do you write with your code?

Postby Quizatzhaderac » Tue Jan 06, 2015 3:57 pm UTC

???
Are you talking to me or Roflwaffle? Rofl explicitly mentions a source control/ ticket system (TFS) and I was suggesting a way to get better use out of it.
The thing about recursion problems is that they tend to contain other recursion problems.

User avatar
Xenomortis
Not actually a special flower.
Posts: 1421
Joined: Thu Oct 11, 2012 8:47 am UTC

Re: What prose do you write with your code?

Postby Xenomortis » Tue Jan 06, 2015 7:20 pm UTC

I somehow missed the TFS and just read "work items".
Parser failure.
Image

User avatar
roflwaffle
Posts: 360
Joined: Wed Jul 01, 2009 6:25 am UTC

Re: What prose do you write with your code?

Postby roflwaffle » Mon Apr 06, 2015 1:59 pm UTC

Quizatzhaderac wrote:Regarding referencing work items: if you need code comments (as opposed to check in comments and associated work items) to help track changes, your classes may be too large/coupled.
They really are. Part of it is that we migrated from Delphi a couple years ago and a lot of our stuff hasn't been converted to classes yet.

The other part, which makes sense to me even if it isn't what we should be doing, is that we hit 2000+ repositories (websites/data plants). Embedding info about the "why" in the comments is a faster way to get an overall idea of what's going on with a particular script than referencing the check in comments/work items.

Arguably, this wouldn't be an issue if we didn't have requirements that constantly change and weren't required to check in code daily, even if it's not ready, but comments that reference work items/design objectives seem to me to be the best solution to our problems even if they're still less than ideal.

User avatar
Quizatzhaderac
Posts: 1554
Joined: Sun Oct 19, 2008 5:28 pm UTC
Location: Space Florida

Re: What prose do you write with your code?

Postby Quizatzhaderac » Mon Apr 06, 2015 2:51 pm UTC

roflwaffle wrote:They really are. Part of it is that we migrated from Delphi a couple years ago and a lot of our stuff hasn't been converted to classes yet.
Make sure people in your office know the term technical debt. Apart from making it more clear there are real problems you want to address, the term helps identify appropriate project management ways to handle it.

Embedding info about the "why" in the comments is a faster way to get an overall idea of what's going on with a particular script than referencing the check in comments/work items.
"Why" is an excellent use of comments. "Which" work item is the dubious part.
The thing about recursion problems is that they tend to contain other recursion problems.

User avatar
roflwaffle
Posts: 360
Joined: Wed Jul 01, 2009 6:25 am UTC

Re: What prose do you write with your code?

Postby roflwaffle » Mon Apr 06, 2015 4:43 pm UTC

The "Which" allows us to compress the "Why" more than we would otherwise, especially since the "Why" in the work item may be buried in a history of 40+ comments. But in general, yeah, our unit (everyone including the business) workflow is kind of broken. We're going through an agile'ish process right now, but we still have many of the same issues and the business is apparently OK with those.

Edit - In general I'd say our system is pretty muddy, and that's because of resource constraints. There are likely issues related to politics as well.

User avatar
SuperJedi224
Posts: 14
Joined: Thu Apr 16, 2015 4:19 pm UTC

Re: What prose do you write with your code?

Postby SuperJedi224 » Sat Apr 18, 2015 12:06 pm UTC

Next to none, actually. I only even bother to add comments if its something that's meant to be changed by someone else, and even then usually only to explain what needs to be changed.
Striving for neutral good while caught in the crossfire of a struggle between lawful stupid, chaotic stupid, and, on occasion, just plain stupid.
Yeah, I'm wearing groucho glasses over a ninja mask. You have a problem with that?

Blutkoete
Posts: 3
Joined: Mon Oct 14, 2013 5:26 am UTC

Re: What prose do you write with your code?

Postby Blutkoete » Mon Apr 20, 2015 8:43 am UTC

Two weeks ago, I found out that documenting your code and filling it up with useful comments doesn't help at all sometimes ... a new colleague came to me asking questions about an old project of mine that he needed to adapt, with every single question he had being answered by my documentation & comments in the code.

He said "I'm sorry, but I'm not used to documentation or code comments being of any value." :(. He didn't even read them because he assumed they are out of date and incomplete.

User avatar
Xenomortis
Not actually a special flower.
Posts: 1421
Joined: Thu Oct 11, 2012 8:47 am UTC

Re: What prose do you write with your code?

Postby Xenomortis » Mon Apr 20, 2015 9:19 am UTC

In his defense, they usually are out of date and incomplete.
Image

User avatar
SPACKlick
Posts: 195
Joined: Wed Apr 03, 2013 11:25 am UTC

Re: What prose do you write with your code?

Postby SPACKlick » Mon Apr 20, 2015 1:50 pm UTC

I don't comment for others, I comment for me.

Why did I do the operators in that order? What sort of timing analysis did I run? What the hell is the point in multiplying this value by minus 1 and then subtracting it from 0 later? If I've done that to solve a problem I at least like to know the problem it solved so when I come back to hatchet job the code into doing something else I can remember why three years ago I made a decision that looks crazy. Was it because I was an even worse coder 3 years ago (key signs of this are comments using word's such as "elegant solution to an annoying problem").

I also really like leaving comments about optimised enough code This section is badly written, it runs once at a rate of over 200hz, don't waste your time fixing it


Return to “Coding”

Who is online

Users browsing this forum: No registered users and 4 guests