816 search results for ""

OCaml Programming Guidelines

OCaml Programming Guidelines

General Guidelines

OCaml Programming Guidelines

Be Simple and Readable

Writing programs law : A program is written once, modified ten times, and read 100 times. So it's beneficial to simplify its writing, always keep future modifications in mind, and never jeopardi

OCaml Programming Guidelines

Naming Complex Arguments

<!-- $MDX skip --> write <!-- $MDX skip --> In place of

OCaml Programming Guidelines

Naming Anonymous Functions

Justification : Much clearer, in particular if the name given to the function is meaningful. <!-- $MDX skip --> write <!-- $MDX skip --> In the case of an iterator whose argument is a comp

OCaml Programming Guidelines

Programming Guidelines

OCaml Programming Guidelines

How to Program

Always put your handiwork back on the bench, then polish it and repolish it.

OCaml Programming Guidelines

Write Simple and Clear Programs

Reread, simplify, and clarify at every stage of creation. Use your head!

OCaml Programming Guidelines

Subdivide Your Programs Into Little Functions

Small functions are easier to master.

OCaml Programming Guidelines

Factor out snippets of repeated code by defining them in separate functions

Sharing code obtained in this way facilitates maintenance, since every correction or improvement automatically spreads throughout the program. Besides, the simple act of isolating and naming a sn

OCaml Programming Guidelines

Never copy-paste code when programming

In conclusion, copy-pasting code leads to programs that are more difficult to read and more difficult to maintain. It must be banished. Moreover, it is difficult to identify that the same ten line

OCaml Programming Guidelines

How to Comment Programs

Avoid comments in the bodies of functions. Prefer one comment at the beginning of the function that explains how a particular algorithm works. Once more, if there is no difficulty, there is no

OCaml Programming Guidelines

Avoid Nocuous Comments

<!-- $MDX skip --> An example of what to avoid, the following comment uses technical words and is thus masquerading as a real comment, but it has no additional information of interest: Absolu

OCaml Programming Guidelines

Usage in Module Interface

The function's usage must appear in the module's interface that exports it, not in the program that implements it. Choose comments as in the OCaml system's interface modules, which will subsequen

OCaml Programming Guidelines

Use Assertions

Note as well that an assertion is often preferable to a comment because it's more trustworthy. An assertion is forced to be pertinent because it is verified upon each execution, while a comment c

OCaml Programming Guidelines

Comments line by line in imperative code

When writing difficult code, and particularly in case of highly imperative code with a lot of memory modifications (physical mutations in data structures), it is sometimes mandatory to comment in

OCaml Programming Guidelines

How to Choose Identifiers

It's hard to choose identifiers whose name evokes the meaning of the corresponding portion of the program. This is why you must devote particular care to this, emphasising clarity and regularity

OCaml Programming Guidelines

Don't use abbreviations for global names

Global identifiers (including the names of functions) can be long because it's important to understand what purpose they serve far from their definition.

OCaml Programming Guidelines

Separate words by underscores: ( int_of_string , not intOfString )

Case modifications are meaningful in OCaml. In effect, capitalised words are reserved for constructors and module names. In contrast, regular variables (functions or identifiers) must start with

OCaml Programming Guidelines

Always give the same name to function arguments which have the same meaning

If necessary, make this nomenclature explicit in a comment at the top of the file. If there are several arguments with the same meaning, then attach numeral suffixes to them.

OCaml Programming Guidelines

Local identifiers can be brief and should be reused from one function to another

A tolerated exception to the recommendation not to use capitalisation to separate words within identifiers when interfacing with existing libraries which use this naming convention. This lets OCa

OCaml Programming Guidelines

How to Use Modules

OCaml Programming Guidelines

Subdividing into modules

For each interface, you must document the things defined by the module: functions, types, exceptions, etc. For each module, you must explicitly write an interface. You must subdivide your program

OCaml Programming Guidelines

Opening modules

<!-- $MDX skip --> Justification : The use of unqualified identifiers is ambiguous and gives rise to difficult-to-detect semantic errors. Avoid open directives, using instead the qualified

OCaml Programming Guidelines

When to use open modules rather than leaving them closed

In a program where type definitions are shared, it's beneficial to gather these definitions into one or more module(s) without implementations (containing only types). Then it's acceptable to sys

OCaml Programming Guidelines

Pattern-Matching

Never be afraid of overusing pattern-matching! On the other hand, be careful to avoid nonexhaustive pattern-matching constructs. Complete them with care, without using a “catch-all” clause su

OCaml Programming Guidelines

Compiler Warnings

Compiler warnings are meant to prevent potential errors, which is why you absolutely must heed them and correct your programs if compiling them produces such warnings. Besides, programs whose com

OCaml Programming Guidelines

Pattern-matching warnings

Nonexhaustive pattern-matches induced by clauses with guards must also be corrected. A typical case consists in suppressing a redundant guard. Justification : It's not really more complicated t

OCaml Programming Guidelines

Destructuring let bindings

let with complex patterns: let [x; y] as l = ... simultaneously defines a list l and its two elements x and y . let with simple pattern: let _ = ... does not define anything, it just

OCaml Programming Guidelines

The destructuring let must be exhaustive

Justification : There is no way to make the pattern-matching exhaustive if you use general destructuring let bindings. <!-- $MDX skip --> Global definition with destructuring let statemen

OCaml Programming Guidelines

Sequence warnings and let _ = ...

Justification : Sequences are much clearer! Compare e1; e2; e3 to In any case, use the let _ = ... construction exactly in those cases where you want to ignore a result. Don't systematicall

OCaml Programming Guidelines

The hd and tl Functions

Justification : This is just as brief as and much clearer than using hd and tl , which must be protected by try... with... to catch the exception that might be raised by these functions.

OCaml Programming Guidelines

Loops

OCaml Programming Guidelines

for loops

Justification : The recursive function lets you code any loop whatsoever simply, even a complex one, e.g., with multiple exit points or with strange index steps (steps depending on a data value

OCaml Programming Guidelines

while loops

Justification : while loops require one or more mutables, so the loop condition changes value and the loop finally terminates. To prove their correctness, you must discover the loop invarian

OCaml Programming Guidelines

Exceptions

Justification : try ... with _ -> silently catches all exceptions, even those which have nothing to do with the computation at hand (for example, an interruption will be captured and the

OCaml Programming Guidelines

Data Structures

The same objection is admissible for enumerated types represented as integers when those integers have an evident interpretation with respect to the represented data. <!-- $MDX skip --> A cont

OCaml Programming Guidelines

When to Use Mutables

Mutable values are useful and sometimes indispensable for simple and clear programming. Nevertheless, you must use them with discernment because OCaml's normal data structures are immutable. They

OCaml Programming Guidelines

Iterators

In case of express need, be sure to add an explanatory comment. In my opinion, it's absolutely necessary! <!-- $MDX skip --> even though you get: <!-- $MDX skip --> On the other hand, avoid w

OCaml Programming Guidelines

How to Optimize Programs

Justification : Clarity and correctness of programs take precedence. Besides, in a substantial program, it is practically impossible to identify a priori the parts of the program whose effic

OCaml Programming Guidelines

How to Choose Between Classes and Modules

Use modules when the data structures are fixed and their functionality is equally fixed or it's enough to add new functions in the programs which use them. Use conventional data structures (in p

OCaml Programming Guidelines

Clarity of OCaml Code

The language features numerous programming styles (or programming paradigms): imperative programming (based on the notion of state and assignment), functional programming (based on the notion of

OCaml Programming Guidelines

Style dangers

Another common “over-imperative error” in the imperative world is not to systematically choose the simple for loop to iterate on a vector's element, but instead to use a complex while loo

OCaml Programming Guidelines

OCaml code generally considered unreadable

If you naturally write the program print_string "Hello world!" in this way, please submit your work to the Obfuscated OCaml Contest . <!-- $MDX skip --> Systematically code sequences with

OCaml Programming Guidelines

Managing Program Development

Below are tips from veteran OCaml programmers that have served in developing the compilers. These are good examples of large, complex programs developed by small teams.

OCaml Programming Guidelines

How to Edit Programs

Developers describe how to use these features: the CTRL-C-CTRL-C combination recompiles the whole application; then, in case of errors, a succession of CTRL-X-` commands permits correction of

OCaml Programming Guidelines

Other Emacs tricks

Under Unix, the CTRL-C-CTRL-C or Meta-X compile combination, followed by CTRL-X-` , is also used to find all occurrences of a certain string in an OCaml program. Instead of launching ma

OCaml Programming Guidelines

How to Edit With the Interactive System

Under Unix: use the line editor ledit , which offers great editing capabilities “à la Emacs” (including ESC-/ !) as well as a history mechanism that lets you retrieve previously-typed comm

OCaml Programming Guidelines

How to Compile

The make utility is indispensable for managing the compilation and recompilation of programs. Sample make files can be found on The Hump . You can also consult the Makefiles for the OCam

OCaml Programming Guidelines

How to Develop as a Team: Version Control

An anonymous Git read-only mirror contains the working sources of the OCaml compilers , and the sources of other software related to OCaml. Users of the Git software version control system