Maintainer Basic Assumptions

Our formal processes describe the things that are required beyond what we think you should "just plain know", or alternatively, what we expect you know without being told. In addition to the things you should have learned in kindergarten (always flush, wash your hands, never lie cheat or steal), and the things in the business code of conduct, there are some things that more directly apply to software engineering that you should know.

First, we develop safety critical software. This is an awesome responsibility. If you don't take your job seriously, people could die. When in doubt; don't assume. Ask someone. If it seems important and they can't point to a place where it is documented, make sure it gets documented. You are now part of the team, there is no "them", you are now part of "us".

Team Culture

Some organizations reward you with the number of problem reports your generate, some punish you. By and large, we don't gather or use metrics that can be so easily manipulated. We expect you to be productive and to follow the rules. We value independent thought and a questioning attitude as long as it leads to a better solution. If you feel embarrassed asking questions, remember the "people will die" reference above and ask yourself what is more important than that?

Collectively you'll find the team is made up of curious, thoughtful, and engaging people. Ideas are more important than who had them (i.e., a meritocracy). Some people think they are funny. Usually they are not. Laughter helps regardless.

Software Culture

At a more concrete level, there are some things that collectively we've found to be helpful and following along will make things easier for everyone concerned.

Since we live in a formal development environment, we expect that you will keep your artifacts in SCM and that you will update them regularly. This obviously has to be balanced against the risk of "breaking the build". Don't break the build, but don't keep things out of CM long periods of time. If you don't know how to balance this, ask someone. We can always branch.

Document how to do things, make sure anyone else can do what you do. This doesn't mean we don't value your unique skills, but the environment we live in requires repeatability. Furthermore, you can't move on to new and more exiting tasks unless someone else can do your old job, or better yet, you've automated yourself into a new job.

If you find a problem or have an idea document it. Problem reports are a fine way to keep track of things to do, and even to use as a general discussion group. However we typically use email and weekly team meetings for initial discussions of problems and ideas, then move on to the wiki for developing proposals, then develop a component which is modified and evolved using the problem reporting system and software configuration management.

Don't do things alone, especially if it is the first time. No one is expected for example, to perform a for-credit, run-for-score for the first time without help from a mentor or senior peer. If you are new, make sure you have a mentor. If one hasn't been assigned, say something about it and we'll get a manager fired.

Collaboration Culture

We are geographically distributed, hence we use technology to communicate and prevent isolation. We expect folks to master these tools:

• An IP phone. Preferably with a headset as we often have long, group discussions. The Mitel phones provide "MiCollab Client" for managing your availability and call forwarding.
• Desktop Sharing. The current preferred solution is Microsoft Teams (https://microsoft365.com).
• Instant Messaging. The team primarily uses Microsoft Chat (part of teams). Please update your Deos_Product_Line_Staff page to share your handle for any means of getting ahold if yout that you wish to share. These tools are used for quick conversations such as "Can I phone you?," and as a way to see who is "at work," or "away."
• Email. Standard format: TJones@ddci.com (first Initial + last name)
• Patch Files and Problem Report Attachments. We are required by our industry to show evidence of peer review. Other organizations often do this with meetings and meeting minutes. We do it by assigning a reviewer and letting that person review and suggest changes to an author's work. These suggested changes are usually in the form of the actual changes, submitted as a patch file to the Problem Report.

Coding and development guidelines

The review process howto refers to various checklists that describe the formal process, including coding expectations. They do not cover things that we just assume you know, or that are strictly speaking not required, but that are generally helpful when everyone does things in a compatible manner.

Things you should already know

Some things are so basic that if you disagree with them, or don't already understand them, you should consider alternate employment.

• Use meaningful names for identifiers.
• Supply meaningful and correct comments.
• Indent your code.
• Duplication is bad.
• Locality of reference is good.
• Document how to do things so that others can do them if you aren't around.
• Don't lie, cheat, or steal.
• etc.

Things you may need to learn

• Zero, one, infinity rule.
• Using invariants, preconditions and postconditions and other informal proof of correctness techniques.
  • Refer to the Design Overview section of the Deos Kernel software requirements document, particularly sections "Design Principles" and "Design and Coding Issues".
• Writing to a spec, not "what works".
• User vs supervisor mode
• Multi-threading, race conditions, and concurrency management
• Assembly programming and basics of compilers
• Virtual vs physical addressing
• Caching and coherency issues, why "naturally aligned" is important
• Memory consistency and ordering
• Design and coding for testability and structural coverage
• Failure modes and the limitations of testing
  • E.g., how to make things fail obvious rather than fail silent or fail sporadically.
  • E.g., why testing for race conditions and memory order is impractical
• Pointer arithmetic, structure overlays and their perils:
  • E.g., some devices do not work with sub-word sized writes and some compiler options don't honor that.
• Endianness
• "volatile" and why/when it is needed.
• Asynchronous nature of hardware in general and CPUs in particular. For example:
  • Why is there a need for SYNC and ISYNC, and what is the difference between them?
  • What is the difference between an exception/interrupt occurs, is raised, is acknowledged, is handled.
• Making things simple is hard, but you need to do it.

Obviously enumerating everything you must know is impossible. Asking about the above is ok (you should always question things you don't understand or agree with, that's another part of our culture), but failing to follow them is unlikely to have a happy outcome.

In general there are also component specific skills. For example:

• To review the kernel x86 HAL, you must be knowledgeable of the kernel HAL design and x86 processor architecture,
• To write CFFS MAL you must know about FLASH and the CFFS MAL API,
• When faced with an arbitrary decision as to where to implement a requirement, prefer user mode first, then Platform Resource Library (PRL) second, Platform Abstraction Library (PAL) third, Deos Boot forth, and the Deos kernel only as a last resort.
• etc.

Style

Some things are more style related:

• Indent with spaces, not tabs (except for makefiles where tabs are required). Note: Some editors like to insert tabs instead of spaces for you, please disable this "feature" on your code editor.
• Put braces "{}" after C/C++ if, while, do, etc. statements.

if (condition) { do stuff... }

if (condition) { 
do stuff... }

if (condition)
{ do stuff... }

if (condition)
{ 
  do stuff... 
}

• Put spaces after keywords, but not after function names, e.g.,

 if (condition)
 {
    function(arg1, arg2, arg3);
 }

• When declaring pointers put "*" next to variable/parameter names, not by type names rationale:

yes: int *var;
not: int* var;

You will not be punished for violating the above, but you should expect to get comments when your code is reviewed. Follow the style of the code around you. Feel free to add your pet peeves..

Tools

In addition to using Eclipse, most maintainers must be familiar with a variety of Unix like tools. Here is a brief description of some useful tools/commands and their common arguments.

bash

Bash is the preferred Unix shell. The following are commands and features that are very common. You can always use the "man" command from the shell to get more info, or use Google.

Common bash features and commands

command	Options	example	Discussion
ls	-l -A -a	ls -lA	List files in a directory
cat		cat foo.txt	output the contents of a file
$		$variable	reference the contents of a variable.
>		ls > foo.txt	Redirection. Put the output of a command into a file.
echo	-n	echo $USER	send to standard output the command arguments.
head	-n	head -n 4 foo.txt	Show the first N lines of a file
sort	-u	sort -u < foo.txt	sort by lines the contents of a file or standard input
grep	-v -i	grep -i aaron foo.txt	search for a string in a file or files
| (pipe)		ls | grep -i mumble	Pipe. Take the output of one command and feed it to the standard input of another command. The example searches for files that have mumble in their name.
find	-type -iname -o	find code -iname '*.h'	Search the filesystem looking for files that satisfy certain characteristics. The examples lists all files that have names that end with .h
for		for v in a b c; do echo $v; done	Execute one or more commands with a variable bound to each of the list of names that are between the "in" and the "; do". The given example outputs three lines.
sed	-e	sed -e 's/foo/bar/'	A Stream EDitor. Make textual replacements based on regular expressions on the contents of the standard input. The given example replaces the first occurrence of the string "foo" with "bar" on each input line.

A more complete example.

 for f in $(find code/ -iname '*.h'); do echo mv $f $(echo $f | sed -e 's/\.h$/.hh/'); done | head

Echo a command that would rename all the .h files in the code subdirectory to be have a type of .hh.

make

Make is the tool used to perform builds of our components. There is a dedicated page for this tool: make.