2

In programming we often create reusable data structures that contain attributes to store information. For example, if writing a piece of software that has to do with cars we may have a Car class that has various attributes like color, make, year, etc. If I am writing about my software is it acceptable to capitalize these class and attribute names?

e.g.

Should the Color attribute in the Car class contain pink?

What does Make mean?

Improve this question
2
  • 2
    In the light of your comment below "I am writing to the people contracting us that have no programming experience.", surely you should be avoiding the use of programming terminology and should be asking questions / writing documentation in English. You're the one they have paid to translate between English & programming languages. But if you really, really must use programming terms, then define/explain them at the beginning so that they understand what these strange-looking camelCase words mean. This is a common-sense question, not an English language question!
    – TrevorD
    Commented Jun 17, 2013 at 23:12
  • @TrevorD Well, I am not really using programming terms. I am using class and attribute names that refer to actual items in their business system. For example, I added filing date to the deed record. For some reason I was feeling the urge to write I added Filing Date to the Deed record because filingDate and Deed are an attribute and class in my code. The message would be short so I don't think I would want to add a header section with definitions as suggested by some below.
    – theblang
    Commented Jul 9, 2013 at 16:21

3 Answers 3

Reset to default
3

Not if the language is case sensitive. You would want to write them in the same way as they were written in your program. For example, if taking about the int type in C, you would want to write int even if it's at the start of a sentence.

(Originally posted as a comment.)

Improve this answer
4
  • Say I had an int yearModel. Do you think I should use yearModel when writing about the program? It seems kind of messy to do that, and the person I am writing to may have no idea that attribute names are often camelCase.
    – theblang
    Commented Jun 17, 2013 at 21:14
  • 3
    Yes, you should. Write them in monospace to distinguish them from the main text, if you want. I would say it's terrible practice to use a different name for attributes in your documentation. (Different capitalization would essentially make it a different name.) Unless you wanted to pleonastically refer to your Color attribute as "the attribute representing color", you should use the same capitalization.
    – Kaiser Octavius
    Commented Jun 17, 2013 at 21:17
  • You are absolutely right about documentation. Sorry, I should have been more specific. I am writing to the people contracting us that have no programming experience.
    – theblang
    Commented Jun 17, 2013 at 21:20
  • In that case I don't see how yearModel would make any sense to them even if written differently. You might want to define yearModel as "Blah blah blah" at the start or something, and refer to it as yearModel throughout the text.
    – Kaiser Octavius
    Commented Jun 17, 2013 at 21:23
2

Normally, you should choose a different font for the program identifiers. For example:

  1. If your normal text is in a nice serif font, then put your code identifiers in an ugly sans instead.

  2. If your normal text is already is an ugly sans, then put your code identifiers in a mono instead.

Improve this answer
5
  • Monospace is best.
    – Kaiser Octavius
    Commented Jun 17, 2013 at 21:17
  • @KaiserOctavius For code excerpts where vertical alignment is paramount, certainly. But when you are simply quoting an identifier, I find that a sans contrasts well enough with a serif, and doesn't screw with your justification at all so badly as mono does.
    – tchrist ♦
    Commented Jun 17, 2013 at 21:27
  • I guess you're right. I was just expressing my love of monospace. =)
    – Kaiser Octavius
    Commented Jun 17, 2013 at 21:29
  • @Kaiser: Don't you mean your love of monospace?
    – J.R.
    Commented Jun 17, 2013 at 21:47
  • :o I guess I do.
    – Kaiser Octavius
    Commented Jun 17, 2013 at 21:47
2

When writing documentation for programmers, it's best to use exactly the names that are in the software to minimize confusion. You can insert extra words to respect capitalization rules. To avoid starting a sentence with the lowercase variable name size, for instance: "Variable size is always less than length."

When writing for a technical audience that probably isn't going to work directly with the program code, use names that maximize readability and follow programming language conventions. It is common for conference papers to use cleaned-up and abbreviated names (of functions, data types, and so forth), as it's generally understood that they're smoothing over messy and boring details to focus on the important parts of the software.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .