The first page of your main code is very important. This file is what first opened and read by reviewers who are not familiar with your code and they open your first source file to orient themselves. Consider following examples when they open your main file:
-
20 lines of copyright/license disclaimer
-
10 lines of
#include ... -
10 lines of constant definition
-
100 lines of data structure definitions
-
sub-function definitions
Those are typical contents for main.c or main.cpp or main.anything and they all offer uninitiated little clues on the overall project. Actually this is often true for any typical source code file. I hate them!
Finally, you search up the main function, it is either several hundred lines long with a bunch of preprocessor conditional switches or meaningless placeholders like this:
MAIN(){
initialization();
processing();
wrap_up();
exiting();
}
There is not really any information there!
For me, always ensure that first-time readers gets the most useful information withing the fist dozens of lines, for example:
include: perl/parse_frame_full.def
include: macros/reduce.def
include: macros/operator.def
include: macros/functions.def
include: macros/compile.def
page: parse_perl
$(if:0)
my $ast = parse_perl("1+2*-3")
print_token($ast)
$(else)
$call get_file_in_t, tests/helloworld.pl
my $ast = parse_perl($t)
print_ast($ast, 0)
compile($ast)
subcode:: parse_setup
$call set_hash, %atom_type, number, string
$call set_hash, %atom_type, exp_fcall
$call set_hash, %atom_type, exp_unary, exp_binary
$call set_hash, %unary_type, '-'
$call set_hash, %non_stmt_boc, fcall, if_cond, while_cond, function_param
fncode: parse_perl($src)
$call parse_frame_full
#----------------------------------------
subcode:: match
...