0

I'm writing documentation for my data analysis framework, and there are classes Histogram and Graph. I document a function that transforms one Histogram to one Graph as

Transform a Histogram to Graph

and I'm not sure whether it is better to use "Graph" with or without an article here.

I searched for examples with 'int' and 'float', and get contradicting results:

To convert an integer to a float

how to convert int to float

I understand they might be non-native speakers.

When I Google, it suggests

People also ask How do you convert an int to a float?

I think that article usage may depend on the frequency of the word's usage (so for int and float it might be different than for my types; but if I assume that users are familiar with my framework?..).

I understand that my question of the programming types might be very narrow, but would be glad for a comprehensive general case it is probably part of. Are articles in programming a local jargon; should I use the "programming convention" (if that exists), or the "grammatically correct" variant (if that exists)?

P.S. Feel free to correct articles in my question, I'm not a native speaker :)

Improve this question
8
  • I found a similar question with the answer "in programming 'String class' could be describing a general programming class called 'String' while 'class String' a specific class called 'String'. So 'objects of the String class' is not necessarily the same as 'objects of class String'." english.stackexchange.com/a/469486/116650 - but I don't completely understand that. Maybe it should be "objects of the string class"? Maybe s.o. else could explain it better just for types (not as that large question I link).
    – Yaroslav Nikitenko
    Oct 7, 2021 at 15:15
  • 1
    It's odd that your expression Transform a Histogram to Graph uses a for Histogram but not for Graph. Use it for both or neither - then the problem goes away? See how the other examples you show us are consistent in their use or non-use of the article (or whatever you want to call a and the).
    – High Performance Mark
    Oct 7, 2021 at 15:25
  • 2
    Are you titling a subroutine? Consider that internal program documentation (called remarks or comments) speaks only to developers. The telegraph style of histogram to graph fits the audience. External documentation speaks to both technical and nontechnical readers. The traditional style of Transform a histogram to a graph fits that more general audience.
    – Yosef Baskin
    Oct 7, 2021 at 15:37
  • @HighPerformanceMark This may sound stupid, but I feel like there is a slight difference between "any histogram" and "the graph". This is like "I saw a squirrel, and the beast was red". However, if you are sure, then I can fix that.
    – Yaroslav Nikitenko
    Oct 7, 2021 at 18:48
  • @YosefBaskin - this is the official documentation (for everyone). I write a library, so this is not for internal usage, but for users of the framework. In fact I already published that, so it looks like this: lena.readthedocs.io/en/latest/… .
    – Yaroslav Nikitenko
    Oct 7, 2021 at 18:51

1 Answer 1

Reset to default
2

I've been programming for over 40 years, and I think both styles are common and idiomatic. But as mentioned in several comments, you should be self-consistent within the sentence, so either

Transform Histogram to Graph

or

Transform a Histogram to a Graph

I believe the reason that it's acceptable without the article is because a type/class name can be used as a collective noun referring to objects of the given type in general. However, I think the form without articles is more often used in synopses, which tend to be terse, rather than the main text of the documentation; it's similar to the way newspaper headlines leave out noise words.

You could also write

Transforms Histograms to Graphs

but this tends to be avoided because the type name is a specific term in the programming language, and adding the plural suffix results in something that doesn't match that term. It could be distinguished using typography, e.g. Histograms, but this looks weird and can also be lost as the documentation is converted to different formats.

Improve this answer
1
  • Thank you, Barmar! I think this answers my question, and I accept this. I'll change my docs when I return to them. It's interesting that both forms are possible (and many thanks for the grammatical explanation for that!), but not together! "You should be self-consistent within the sentence" - I'll pay attention to that if I find this rule in grammar books next time!
    – Yaroslav Nikitenko
    Oct 9, 2021 at 12:31

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.