Elektra 0.11.0
keyCopy

Signature

int keyCopy(Key *dest, const Key *source);

Checklist

Doxygen

  • first line explains briefly what the function does
    • Clear -> clear
    • do not instantly reference keyDup
  • @see
    • add @see for keyDup
  • @since (optional: for after 1.0.0)
    • add @since 0.9.5
  • @ingroup
  • @retval
    • use retval instead of return (see snippet below)
  • good example or snippet how to use the function
    • move example to keyDup
  • simple examples go first
    • move simple example to the top
  • Precondition
    • add precondition (valid key values)
    • Precondition
      dest must be a valid Key (created with keyNew)
    • Precondition
      source must be a valid Key or NULL
  • Postcondition
    • add postcondition
    • Postcondition
      Value is written to key dest
  • Invariant
    • add invariant
    • Key name stays valid (document at struct)
    • Key name stays valid until delete
  • @param for every parameter

    • better describe flags (|)

    invariants?

invariants?

@retval dest
@retval NULL in case of error

Naming

  • Abbreviations used in function names must be defined in the Glossary src/libs/elektra/symbols.map
  • Function names should neither be too long, nor too short
  • Function name should be clear and unambiguous
  • Abbreviations used in parameter names must be defined in the Glossary
    • add dest to glossary - maybe rename dest to destination?
  • Parameter names should neither be too long, nor too short
  • Parameter names should be clear and unambiguous

Compatibility

  • ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine)

Parameter & Return Types

  • Functions should return the most specific type possible
  • Functions should require the most general type possible
  • Function parameters should use enum types instead of boolean types wherever sensible
  • Wherever possible, function parameters should be const
  • Wherever possible, return types should be const
  • Functions should have the least amount of parameters feasible

Structural Clarity

  • Functions should do exactly one thing
    • remove keySetName keySetRaw ksClear functionality from keyCopy?
  • Function name has the appropriate prefix
  • Signature in kdb.h.in has same order as Doxygen docu
  • No functions with similar purpose exist
    • keyCopyAllMeta

Memory Management

  • Memory Management should be handled by the function wherever possible

Extensibility

  • Function is easily extensible, e.g., with flags
  • Documentation does not impose limits, that would hinder further extensions
    • KEY_CP_ALL equivalent to KEY_CP_NAME | KEY_CP_VALUE | KEY_CP_META

Tests

  • All possible error states are covered by tests and documented
  • All possible enum values are covered by tests
    • use flags other than KEY_CP_ALL
  • No inconsistencies between tests and documentation
  • Functions should have no side effects (idempotency)

Summary

Other Issues discovered (unrelated to function)