2

As someone whose mother tongue is not English, I'm sometimes having a hard time having the correct feeling towards the meaning of some words. This is one of those situations.

I'm looking for a term that refers to how an API (an application programming interface) is designed. For example imagine a piece of text with such statements:

  • For every *_new function, there is a *_delete function.
  • All functions creating shared objects take a name parameter as the first argument.
  • All int *error arguments used for returning error code are optional and come last in the argument list.

How do you refer to the text containing these statements? For example, is it the style definition of the API? Are these the conventions of the API?

|improve this question
  • Naming conventions for identifiers sounds good. – tchrist♦ Mar 21 '13 at 15:35
  • @tchrist, I have seen naming conventions before, it's quite common. This is a bit different though. For example the fact that "the error argument comes last and is optional" isn't really a "naming" convention. – Shahbaz Mar 21 '13 at 15:43
  • Possibly too-localized for ELU. Have you already asked on SO? – Kris Mar 22 '13 at 7:03
  • @Kris, I'm active on SO myself, but I have never seen such questions there. I'm getting more meaningful answers here though, for example an answer such as Jim's would probably not show up in SO. – Shahbaz Mar 22 '13 at 13:54
4

They are referred to as "Coding standards" in the software engineering world.

|improve this answer
2

You might be looking for design template or design pattern.

Design patterns are not frequently associated with interfaces, but the term does come up, as with the "facade design pattern".

From wikipedia:

A facade is an object that provides a simplified interface to a larger body of code, such as a class library.

Simplification comes from creating reusable and familiar patterns that meet the necessary functional requirements.

You may like to know that "design patterns" is not localized to just software development. It was codified as an architectural concept by Christopher Alexander, and his ideas were published in "The Timeless Way of Building" in 1979. This book is literally about the architecture of buildings and construction, but lays a foundation for applying the concept to other fields of design.

Incidently, while on the subject of architecture, the word archetype, comes to mind as well (although the words are not related directly).

Archetype: the original pattern or model of which all things of the same type are representations or copies

But I don't think you will see "archetype" used as frequently in this case.

|improve this answer
  • 1
    I think this answer is genuinely wrong. A design pattern is an abstraction, by intention independent of implementation details such as code orthography. What the OP is describing is a concrete and specific set of low-level rules. These are, as moonstar2001 states, coding standards or coding conventions. – walkytalky Oct 28 '14 at 11:12
2

if you wanted to describe an implementation as being proper example of a given style you could use "idiomatic".

"That is an idiomatic example of a RESTful archtitecture"

Merriam Webster

1: of, relating to, or conforming to idiom

2: peculiar to a particular group, individual, or style

|improve this answer
0

The list shown 'specifies' a series of realities of the API; ie it is a 'specification'. There is no room for discussion, it states a series of facts about 'specific' things. Specification language is a very standardised and accepted form of English intended to be as clear as possible for the purpose of imparting important information. It is almost an attempt to write computer code in plain English :-) What makes it easy to recognise in a good example is what is missing:
no colloquialisms, first- or second-person modes or humour; no decoration or variety (the same sentence format is factored out and used to achieve the same purpose each time it is needed); no sarcasm, irony or exaggeration (care is taken to minimise assumptions by the reader, e.g. abbreviations are expanded locally or adjacent, punctuation is avoided where possible because misreading it can affect the meaning). The words 'Required' and 'Shall' may be used to give a special authority to some statements.

|improve this answer

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.