From: Thomas Walker Lynch Date: Mon, 9 Mar 2026 08:05:36 +0000 (+0000) Subject: doc tweaks X-Git-Url: https://git.reasoningtechnology.com/%5B%5E?a=commitdiff_plain;h=4665007c1e651c7bd6db1105d179b658364cb86c;p=Harmony doc tweaks --- diff --git a/developer/document/File and directory naming conventions.html b/developer/document/File and directory naming conventions.html deleted file mode 100644 index afa4ad3..0000000 --- a/developer/document/File and directory naming conventions.html +++ /dev/null @@ -1,55 +0,0 @@ - - - - - File and directory naming conventions - - - - - - - - -

Case

- Directory and file names follow the exact same casing rules as the identifiers they represent. Because standard file systems support the hyphen (-), file and directory names use snake-kebab_case for functions and scripts, and PascalCase for types and modules. The hyphen serves as the primary word separator, while the underscore (_) is reserved for structural or namespace boundaries. (Currently many file names use primarily `_`, but we will transition to this more uniform approach.) -

- -

Directory properties

- A directory name is taken as a property for a set of files. Consequently, directory names are rarely plural. For example, suppose we have a number of test files in a directory. The directory would be named test, as each file in the directory has the property of being a test. -

- What is a reasonable primary property for a set of files? Perhaps: -

Who uses each file with this property. Home directories are named like this.
The role of the people using the file. The developer and tester directories were named in this manner.
What program are the files for.
The generic category of program said files are for. We prefer the names authored and made. authored files are those written by humans or AI, while made files are products of tools.

- -

Dot extensions as properties

- We add a second property to a file using dot extensions to the file's name. We can extend the dot suffix model by using multiple dot suffixes. File name extensions are used to signal to the build tools how the file is to be processed: -

.cli.c : Compiler fodder made into a stand-alone executable.
.lib.c : Library code source, compiled as an object file and added to the project archive.
.mod.c : Kernel module sources.

- -

C source file structure

- The RT C coding environment does not use separate source and header files. Each module has an Interface section and an Implementation section in the same file. A preprocessor macro (e.g., FACE) is used to gate off the implementation if the source code is to be used as a header. -

- - - diff --git a/developer/document/File_directory_naming.html b/developer/document/File_directory_naming.html new file mode 100644 index 0000000..6de0ede --- /dev/null +++ b/developer/document/File_directory_naming.html @@ -0,0 +1,77 @@ + + + + + File and directory naming conventions + + + + + + + + +

Program file system objects

+ +

+ Harmony files and directories are considered to be program file systems objects. +

+ +

Files

+ Files that hold a single class, have he same base name as that class. If a file holds multiple classes, but there is a class of primary importance and auxiliary classes, the file carries the name of the primary class. +

+ +

+ If a file represents a module or name space, follow the same naming conventions specified for classes and name spaces in the RT_code_format.html document. +

+ +

+ Other program files follow the same naming conventions specified in the RT_code_format.html document for an identifier of the + contained or related language. +

+ +

Hyphens and spaces

+ +

In a C language culture, file names use underscores between words. In a Lisp language culture use snake-kebab_case. Spaces are generally not used in program file names. +

+ + +

Program Directories

+ A directory that is a package, follows the convention for name spaces. +

+ +

+ A directory that is used to give the contained files a property is an identifier. +

+ +

+ What is a reasonable primary property for a set of files? Perhaps: +

Who uses each file with this property. Home directories are named like this.
The role of the people using the file. The developer and tester directories were named in this manner.
What program are the files for.
The generic category of program said files are for. We prefer the names authored and made. authored files are those written by humans or AI, while made files are products of tools.

+ +

Property indicators on files

+ We add a second property to a file using dot extensions to the file's name. We can extend the dot suffix model by using multiple dot suffixes. File name extensions are used to signal to the build tools how the file is to be processed: +

.cli.c : Compiler fodder made into a stand-alone executable.
.lib.c : Library code source, compiled as an object file and added to the project archive.
.mod.c : Kernel module sources.

+ + + + diff --git a/developer/document/RT_code_format.html b/developer/document/RT_code_format.html index d9085a2..e01c98d 100644 --- a/developer/document/RT_code_format.html +++ b/developer/document/RT_code_format.html @@ -109,12 +109,10 @@ } -

This rule is not applied to function calls in Lisp.

- -

Short stuff rule

If a statement can fit on a single line and is short, keep it on a single line without braces.

This rule is not applied to function calls in Lisp. For example, the outer parentheses forming a function call receive no padding, even when they contain nested data lists:

+ - if(x == 0) return; + (cat 'a 'b '( 2 (4 5)))