-1

I am writing an API with some mandatory parameters and some optional parameters. However, some of the optional parameters are highly recommended to the point of being essentially mandatory for any type of practical interaction with the API unless the user is very skilled with his queries. How would I thus word the three categories of options:

  1. Mandatory
  2. Recommended
  3. Optional

or

  1. Mandatory
  2. Optional But Recommended
  3. Really Optional

or

something else? What do you suggest?

The first list is a bit unclear in my opinion, but the second list is too wordy. Is there a word which embodies Optional but recommended? Note that my preference would be two categories (Mandatory and Optional), but it seems that users need this distinction to be made.

Improve this question
7
  • I think you've answered your own question. My suggestion would have been "Highly Recommended" (or, perhaps even better: "Strongly Recommended").
    – J.R.
    Nov 28, 2012 at 10:21
  • Can I tell you I will love you forever for documenting this kind of gradation?
    – SF.
    Nov 28, 2012 at 10:22
  • 2
    Maybe the folks at Software Engineering would be able to suggest something for you?
    – Matt E. Эллен
    Nov 28, 2012 at 10:31
  • "Is there a word which embodies Optional but recommended?" -> Well, the word recommended does imply optional, not necessary. But it is a hint that you should do this part for your own advantage.
    – Em1
    Nov 28, 2012 at 11:16
  • 1
    I think this question is Off Topic here, and should be migrated to SO User Experience.
    – FumbleFingers
    Nov 28, 2012 at 14:34

5 Answers 5

Reset to default
-1

What about Mandatory, Recommended, and Discretionary?

Improve this answer
1
  • Thanks, this looks to be about as close as I'll be able to come.
    – dotancohen
    Nov 28, 2012 at 14:39
2

You're confusing things. Mandatory and optional are specifically what is truly mandatory or optional for the function to be called. Your recommendations etc. go into usage section, where you can state all the nuances. Thus the mandatory and optional specify what is legal to use in the API without getting errors.

Improve this answer
2
  • Thank you Chris. I'm not confusing things, but I don't want to address the nuance because it is a red herring to the question of which word is appropriate.
    – dotancohen
    Nov 28, 2012 at 21:11
  • Software manuals use the terms required/optional in the context of what is the actual conditions controlling the logic of user supplied parameters. Btw it's required instead of mandatory, as you can require the parameters but not mandate them to anyone. it's a software manual not government policy. I've read a lot of software manuals in my time and all function calling conventions are written this specific way so that it's clear at the basal level what the software allows or not. Otherwise you muddy what software accepts and what's good vs bad vs ugly according to you.
    – Chris
    Nov 28, 2012 at 23:49
1

"recommended" implies that it is optional, but I don't really ever remember reading a doc that specifies a recommended parameter.

typically a doc will say, if n is NULL then the code tries to figure out that value by doing x, y, and z.

Improve this answer
0

Programmers are used to only seeing two levels regarding parameters. Required and optional. The code will reject any request that is missing required parameters. The code will then use default values for the optional parameters. These default values are then documented so the programmer knows what to expect.

Unfortunately there doesn't seem to be room for a third option. The code is expected to function without these "recommended" parameters and must use the default values.

The best approach may be a different or overloaded method that has more required parameters but allows greater control. For example a basic method that assumes many defaults, and one that allows for many more options. You see that with some search methods that will search by keyword only for the simple command, and let you specify the folder, date...for the advanced command.

Improve this answer
3
  • In my work we had a system where we'd build "modules", self-contained blocks of logic+visuals of a single piece of a page (separation of logic from presentation was only inside the module), which would take sometimes 30-40 parameters, from which 1-3 would be mandatory, 10 or so recommended and the rest only usable in very exceptional situations. Even the mandatory ones weren't really, you'd just get placeholders instead of valid content. But the reality was that everyone was used to at least three levels of necessity.
    – SF.
    Nov 28, 2012 at 11:50
  • The code knows that something is either needed or not, but the users need to differentiate between "needed 98% of the time" to between "needed 2% of the time". Whether or not those users read "PHP in 24 hours", they still need the difference to be made clear, concisely in a list title.
    – dotancohen
    Nov 28, 2012 at 13:02
  • By the way, the downvote wasn't me! I disagree with you, but I'm glad that you put forward your opinion.
    – dotancohen
    Nov 28, 2012 at 13:06
-1

I wonder if Essential would fit the bill.

from Merriam-Webster:

2 a : of the utmost importance : basic, indispensable, necessary <an essential requirement for admission to college>

"You'd better know what you're doing if you're skipping this!"

Improve this answer
3
  • 1
    I think that Essential implies that the parameter is mandatory. I am looking for a word less strict than mandatory, but stricter than optional. Essential seems even more strict than mandatory.
    – dotancohen
    Nov 28, 2012 at 11:14
  • @dotancohen: Microsoft Security Essentials aren't mandatory or even necessary to be secure.
    – SF.
    Nov 28, 2012 at 11:42
  • You could also go with "Essential, Important, Recommended, Optional and Deprecated" as a scale of recommendation instead of overlapping it onto the binary system of "mandatory/optional".
    – SF.
    Nov 28, 2012 at 11:52

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