Using Spatial Words Can Help Kids Be More Comfortable With STEM

I like the below news story:

The way you talk with your child can help them to understand science and math
https://wkow.com/news/top-stories/2018/12/24/the-way-you-talk-with-your-child-can-help-them-to-understand-science-and-math/

Although there are two points that I would like to consider:

1. I suspect that the additional time spent with your kids has a bigger impact than the subject matter.
2. The story focused on very little kids with concepts that they will almost definitely will pick up later if you don't introduce those ideas. However, if they are the last ones to learn those concepts then they might be embarrassed and will shy away from Science, Technology, Engineering, and Mathematics (STEM).

I know adults that would be hesitant about which way to turn an object if I said, "Please rotate that to the left." They definitely can figure it out but they are not comfortable with the language.

Of course, the same phrase, "rotate to the left," could mean something different to someone from a different part of the world but that consideration is about teaching to consider context.

You might be thinking that this is a silly little thing to put any thought into but imagine what it means to rotate an array to the left or right. Or to rotate a multidimensional array. You quickly start to get into college level computer science and mathematics. And we're still just talking about how to orientate your perspective.

Anyway, I like this story because at the heart of the news story is encouragement for parents to spend more time with their kids and to impart their knowledge.

Provide All The Information The User Needs And Nothing More

A key part of the design process is the precise definition of each and every software component in the system. This specification will become the "public" part of the component. It must include everything a user needs, such as its purpose, its name, its method of invocation, and details of how it communicates with its environment. Anything that the user does not need should be specifically excluded. In most cases, the algorithms and internal data structures used should be excluded. For if these were "visible," users might utilize this information. Subsequent enhancement or modification then becomes profoundly more difficult because any change to the component has a cascading effect on all components that use it (related to encapsulation).


Reference:
Parnas, D., "A Technique for Software Module Specification with Examples," CACM (May 1972).

Use Efficient Algorithms

Knowledge of the theory of algorithm complexity is an absolute prerequisite for being a good designer. Given any specific problem, you could specify an infinite number of alternative algorithms to solve it. The theory of "analysis of algorithms" provides us with the knowledge of how to differentiate between algorithms that will be inherently slow (regardless of how well they are coded) and those that will be orders of magnitude faster. Dozens of excellent books exist on this subject. Every good undergraduate computer science program will offer a course on it.


Reference:
Horowitz, E. and Sahni, S., Fundamentals of Computer Algorithms, Potomac, MD: Computer Science Press, 1978.

Howl's Moving Castle

Howl's Moving Castle by Diana Wynne Jones
My rating: 5 of 5 stars

Just as another reviewer said the movie made me want to read the book. The catch is either I don't remember the movie or the book is different enough that I can't link them in my mind. Doesn't really matter. I enjoyed the book. I think Calcifer was my favorite character. I'd like to know why he fell.

View all my reviews

Gather 'Round the Sound

Gather 'Round the Sound by Paulo Coelho
My rating: 3 of 5 stars

Good short stories that fit the season. Be warned the first story, "12345," is a bit of a tear jerker.

View all my reviews

Light Falls: Space, Time, and an Obsession of Einstein

Light Falls: Space, Time, and an Obsession of Einstein by Brian Greene
My rating: 5 of 5 stars

Exciting and revealing. Provides insight into the passion that drove Einstein while working on a theory of general relativity.

View all my reviews

Write Programs For People First

In the early days of computing, computers were relatively slow. Almost anything that could be done to shave off a few instructions was worth the effort. The most efficient use of any of the resources on the very expensive computer system was the major goal. Things have changed. The most valuable resources is now people: people to develop the software, people to maintain the software, and people to enhance capability. With few application exceptions, programmers should think first of the people who will later attempt to understand and adapt the software. Anything that can be done to assist them should be done.¹ Efficiency is also important,² but they are not mutually exclusive. If you need efficiency, that's fine but upgrade the readability of your program so that you don't lose the humans in the process.

1. Avoid Tricks
   Avoid Global Variables
   Write To Read Top-Down
   Avoid Side-Effects
   Use Meaningful Names
2. Evaluate Alternatives
   Use Efficient Algorithms
   Get It Right Before You Make It Faster

Reference:
McConnell, S., Code Complete, Redmond, WA: Microsoft Press, 1993.

Use Meaningful Names

Some programmers insist on naming variables with names like nflt or nFlight. The usual argument is that it makes programmers more productive because of reduced key presses. Good programmers should spend a very small percentage of their time typing (maybe 10 to 15 percent); most time should be spent thinking. So how much time is really being saved?

A better argument is that overly shortened names actually decrease productivity. There are two reasons:

1. Testing and maintenance costs rise because people spend time trying to decode names, and
2. more time is spent typing comments to explain the shortened names!

Reference:

Ledgard, H., Programming Proverbs, Rochelle Park, NJ: Hayden Book Company, 1975.

Avoid Side-Effects

A side-effect of a procedure is something the procedure does that is not its main purpose and that is visible (or whose results are perceivable) from outside the procedure. Side-effects are the sources of many subtle errors in software, that is, the ones that are the most latent and the ones that are most difficult to discover once their symptoms manifest themselves.


Reference:
Ledgard, H., Programming Proverbs, Rochelle Park, NJ: Hayden Book Company, 1975.

The Whole Art of Detection

The Whole Art of Detection: Lost Mysteries of Sherlock Holmes by Lyndsay Faye
My rating: 4 of 5 stars

I enjoyed Lyndsay Faye's style. She makes Sherlock Holmes into a little bit more of a gentleman, which is pretty cool.

This book follows a journal format and skips back and forth with regard to time and sometimes point-of-view. I imagine that in the print version there is whitespace that indicates a context switch. However, in the audiobook, there really isn't much of a warning.

Overall, a good book. I want more Sherlock Holmes!

View all my reviews

Write To Read Top-Down

People generally read a program from top to bottom. Write your programs to help others understand them. Among the implications of this principle are:

1. Include a detailed external specification up front to clearly define the program purpose and use.
2. Specify externally accessed routines, variables, and algorithms up front.
3. Use the "structured" programming constructs, which are inherently easier to follow.

Reference:

Kernigham, B., and Plauger, P., The Elements of Programming Style, New York: McGraw-Hill, 1978.

Avoid Global Variables

Global variables make it convenient to write programs; after all, if you need to access or change x, you just do it. Unfortunately, if x is ever accessed and found to have an inappropriate value, it is difficult to determine which software component is at fault. "Global" implies that anybody could have altered its value incorrectly.

As an alternative, encapsulate important data in its own module, so that anybody who wants to change it or access it must do so by means of that routine. Alternatively, explicitly pass parameters to routines that need specific data. If you find an excessive number of parameters, perhaps your design needs to be reworked.


Reference:
Ledgard, H., Programming Practice, Vol II, Reading, MA: Addison-Wesley, 1987.

Avoid Tricks

Many programmers love to create programs with tricks. These are constructs that perform a function correctly, but in a particularly obscure manner. Typically, they use a side-effect of a function to implement a primary function. Programmers see these as "clever," but, as Allen Macro points out, they "are often merely the stupid use of high intelligence."
    There are many ways to explain why tricks are used so often:

1. Programmers are extremely intelligent and want to demonstrate that intelligence.
2. Maintainers, when they finally figure out how the trick works, will not only recognize how smart the original programmer was, but also will realize how smart they themselves are.
3. Job security.

Bottom line: Show the world how smart you are by avoiding tricky code!

Reference:

Macro, A., Software Engineering: Concepts and Management, Englewood Cliffs, NJ: Prentice-Hall International, 1990.

Software Reliability Can Be Achieved Through Redundancy

In hardware systems, high reliability or availability (Specify Reliability Specifically) is often achieved through redundancy. Thus, if a system component is expected to exhibit a mean-time-between-failures of x, we can manufacture two or three such components and run them in either:

1. Parallel. For example, they all do all the work and, when their responses differ, one is turned off with no impact on overall system functionality.
2. Or cold standby. A backup computer might be powered on only when a hardware failure is detected in the operational computer.

Manufacturing cost is slightly more than doubled. Design cost increases slightly. Reliability increases exponentially.

    In software systems, we cannot use the same approach. If we make two copies of the same software, no increase in reliability will be achieved. In one fails, the other will as well. What can be done, however, is to design (using two different design teams) two versions of the software from the same requirements specification, and deploy them in parallel. Development cost doubles. Reliability increases exponentially. Notice that, in the case of hardware, design increases in cost only slightly, whereas software design cost (the primary cost of software) doubles. Ultrahigh reliability in software is very expensive (High Quality Software Is Possible).

Reference:

Musa, J., et al., Software Reliability, New York: McGraw Hill, 1987.

"Garbage In, Garbage Out" Is Incorrect

Many people quote the expression "garbage in, garbage out" as if it were acceptable for software to behave like this. It is not. If a user provides invalid input data, the program should respond with an intelligent message that describes why the input was invalid. If a software component receives invalid data, it should not process it, but instead should return an error code back to the component that transmitted the invalid data. This mindset helps diminish the domino effect caused by software faults and makes it easier to determine error causes by 1) catching the fault early and 2) preventing subsequent data corruption.


Reference:
McConnell, S., Code Complete, Redmond, WA: Microsoft Press, 1993.

Imposter Syndrome

All fields have some amount of imposter syndrome. It happens in Software Engineering a lot. Constantly changing technologies and changing projects can catch a person off-guard and overwhelm them. Often the problem is only in your head. You actually are doing fine, or would be if you gave yourself a chance. Peter J. Denning wrote an excellent article about this called The Beginner's Creed. The creed is all about learning to be expert beginners so new technologies and projects don't overwhelm us.

You Can Reuse Without A Big Investment

When salvaging you got to be the tug that pulls what you need to the surface.

The most effective way to reuse software components is from a repository of crafted, handpicked libraries that were tailored specifically for reuse. However, this requires considerable investment in both time and money. It is possible to reuse in the short term through a technique called salvaging.

Salvaging is asking others in your organization if they have built a software component that does X. You find it, you adapt it, you employ it. This may not be efficient in the long term, but it certainly works now; and then you have no more excuses not to reuse.

To my experience, few organizations are willing to allocate time for the proper care and upkeep of a repository of reusable software components. Salvaging might be your only option. And it gets you talking to your peers on different teams. This communication is like grease that will make future interactions smoother.

Know Your Application

No matter how well the requirements have been written, the selection of optimal architectures and algorithms is very much a function of knowing the unique characteristics of an application. Expected behavior under stress situations, expected frequency of inputs, life-critical nature of response times, likelihood of new hardware, impact of weather on expected system performance, and so on are all application-specific and often demand a specific subset of possible alternative architectures and algorithms.


Reference:
Curtis, B., et al, "A Field Study of the Software Design Process for Large Systems," CACM, November 1988.

Store Requirements in a Database

Keep in mind that the follow quote is from 1995. It is still completely relevant.

Requirements are complex and highly volatile. For these reasons, storing them in electronic media, preferably a database, is a good idea. This will facilitate making changes, finding implications of changes, recording attributes of specific requirements, and so on.
      Some of the things you want to store in the database are unique identifier (Separately Number Every Requirement), the text of the requirement, its relationship to other requirements (such as more abstract or more detailed descriptions of the requirement), importance (Prioritize Requirements), expected volatility, pointers to its sources (Record Why Requirements Were Included), applicable product versions (Identify Subsets and Give Every Intermediate Product a Name and Version*), and so on. Ideally, the requirements specification itself is nothing but an organized "dump" of the entire database.

I have used JIRA. There are many tools like it. They can do all of the above, but it is up to the person creating a ticket in JIRA to ensure those things are done. I think they are really important so I'm going to list them again.

• Create the ticket in a backlog or project that is unique. Do not lump unrelated tickets together. This will result in a "fatlog" - a fat backlog that is difficult to groom and manage.
• The text of the requirement goes in the "description". The "summary" is not where the requirement should be detailed. Personally, I think systems like JIRA should not allow tickets that have no description to be saved. Engineers should refuse to estimate such tickets and Product Owners who create them should be ashamed.
• JIRA has a feature to link tickets. Use it. If there is a dependency then utilize the sub-task feature. Make a story that encapsulates both tickets and make them linked sub-tasks. Use the system to track if everything for that requirement is actually done.
• Order the tickets by importance. There can only be one highest priority and it at the top.
• Use comments to document the sources/stakeholders for a ticket. Do not use comments to have a discussion about a ticket. Email, call, instance message, etc with the people involved. If you absolutely must use the comments section of a ticket to have a discussion then clean it up later. Delete anything that will mislead people reading the ticket. If you want to save the history then move that stuff into a document and attach it to the ticket with a title that makes it clear that it is for history and it is not the requirement. The actual requirement is in the description.
• Ensure that you put what product the ticket applies to either in the summary or the description. You might be inclined to think that it is clear by where the ticket sits. For example, the ticket is in the product A backlog. Invariability, someone is going to get confused and try to work that ticket for product C which is really similar to product A. I've also seen people accidentally move a ticket to a different backlog then not be able to figure out where it belonged.
• If you can't take the issues in a JIRA backlog and print them out in order and call that your software requirements specification (SRS) then your backlog is a mess and you have some work todo.

6 Tips to Make Your Backlog Lean

Self-Destruct TBDs

A software requirements specification (SRS) with a TODO or TBD (To Be Determined) note is obviously not complete. There may be good reasons for approving and starting work on a project with a TBDs in the specification. This is particularly true for requirements whose precision are not critical to fundamental design decisions.

When you create a TBD, be sure to footnote it with a "self-destruction note," that is, specify who will resolve the TBD and by when.


Reference:
IEEE, ANSI/IEEE Guide to Software Requirements Specifications, IEEE Computer Society Press, Washington, DC, 1994.

Specify When Environment Violates "Acceptable" Behavior

Requirements specifications often define characteristics of the system's environment. This information is used in making intelligent design decisions. It also often implies that the developer is contractually obligated to accommodate such characteristics. What happens after deployment when the environment exceeds the specified limits?

Suppose the requirements for an air traffic controller system specify that the system shall handle up to 100 aircraft in a sector simultaneously. They system is built and correctly satisfies this requirement. Three years later 101 aircraft accidentally enter a sector. What should the software do? The possibilities are:

1. Print an error message.
2. Crash.
3. Ignore the 101st aircraft.
4. Process all 101 aircraft but perhaps not satisfy some other timing constraint (such as how often the screen is updated).

Obviously, options 1, 2, and 3 are unacceptable. Yet they are valid system responses as (not) stated in the requirements. The right solution is to explicitly state in the software requirements specification (SRS) the expected system response when the environment exceeds any of the constraints defined for it.


Reference:
Davis, A., Software Requirements: Objects, Functions, and States, Prentice Hall, Englewood Cliffs, 1993.

Specify Reliability Specifically

Software reliability is difficult to specify. Don't make the problem even more difficult by being vague. For example, "The system shall be 99.999% reliable" means nothing.

Does it mean that the system cannot be "down" more often than 5 minutes every year but that it is okay to occasionally make a mistake (for example, a hotel reservation service may occasionally mix up hotel details). Or does it mean that it must make no more than one mistake every 100,000 transactions (for instance, a patient monitoring system cannot cause the death of more than one out of every 100,000 patients)?

When writing requirements, differentiate between:

1. Failure on demand.
•  What is the likelihood, measured as a percentage of requests, that the system will fail to respond correctly? For example, "The system shall correctly display 99.999% of hotel information."
  
2. Rate of failure.
•  This is the same as "failure on demand" but it is measured as a percentage of time. For example, "The system may fail to report hotel information correctly no more than twice a year."
3. Availability.
•  What percentage of time may the system be unavailable for use? For example, "The hotel reservation system shall be available 99.99% of the time in any given calendar year."

Reference:
Sommerville, I., "Software Engineering," Addison-Wesley, Reading, MA, 1992.

Write Natural Language Before a More Formal Model

Augment, Never Replace, Natural Language says to create requirements specifications that contain both natural language and formal models. Let's go a step further: Always create the natural language version of a requirements specification first. If you write the formal model first, the tendency will be to write the natural language that describes the model instead of the desired system. This also applies to writing test cases. Write the test cases first to avoid the tendency to only test the code that was written or the way it is applied.

The best approach is to (1) write the natural language, (2) write the formal model, and (3) adapt the natural language to reduce ambiguities that become apparent when writing the formal model.

Augment, Never Replace, Natural Language

"In an effort to reduce ambiguity in requirements, software developers often decide to use a notation that is more precise than natural language. This is, of course, commendable in that ambiguity is reduced (Reduce Ambiguity in Requirements) by using finite state machines, predicate logic, Petri nets, statecharts, and the like. However, in such an effort, the specification is rendered less understandable by others (Keep the Requirements Specification Readable*) who may have less computer science or mathematical background than the requirements writer.

To alleviate this problem when using a formal notation, retain the natural language specification. In fact, one good idea is to keep the natural language and more formal specification side-by-side on opposing pages. Do a manual check between the two to verify conformity. The results will be that all readers can understand something and that some nonmathematical readers may learn something useful."


Reference:
Meyer, B., "On Formalism in Specifications," IEEE Software, January 1985.

Reduce Ambiguity in Requirements

Software requirements specifications are often written in a natural language. To reduce the ambiguity of natural language apply the following techniques:

1. Performing Fagan-type inspections on the Software Requirements Specification (SRS).
2. Constructing formal models of the requirements and rewriting the natural language as problems are found (Know Formal Methods).

Reference:
Davis, A., "Software Requirements: Objects, Functions, and States," Prentice Hall, Englewood Cliffs, 1993.

Separately Number Every Requirement

"It is essential that every requirement in the requirements specification be easily referenceable. This is necessary to enable later tracing to the requirements from the design (Trace Design to Requirements) and from test (Trace Tests to Requirements)."

I recently completed a project where there was not requirements specification document. The requirements were captured in a JIRA project. For anyone using a similar system for requirements tracking, the equivalent principle would be to make a ticket for every requirement. Don't get lazy and lump several requirements into one ticket just because they are related. If they are separate requirements then they need to be tracked as separate tickets.


Reference:
Gilb, T., "Principles of Software Engineering Management," Addison-Wesley, Reading, Mass, 1988.

Write Concisely

I often see requirements specifications with sentences like:

The target tracking function shall provide the capability to display the current tracking coordinates of all active targets.

Contrast this with:

When tracking, the system shall display the current positions of all active targets.

Organize Requirements Sensibly

Organize requirements in a way most natural for the customers, users, or marketing personnel. This will help avoid later changes or additions by improving understanding of what is being requested.


Reference:
Davis, A., "Software Requirements: Objects, Functions, and States," Prentice Hall, 1993.

Use Multiple Views of Requirements

Multiple views of requirements are needed to sufficiently understand or describe the behavior of a complex system. For example, you might use object-oriented analysis (OOA) to assess the real-world entities relevant to an application. OOA will help identify them and understand their interrelationships and attributes. You might use finite-state machines to describe the desired behavior. You might use decision trees to describe the system's behavior in response to complex input, and so on.


Reference:
Yeh, R., "Software Requirements: New Directions and Perspectives," Handbook of Software Engineering, New York. 1984.

Keep the Requirements Specification Readable

A requirements specification must be read and understood by a wide range of individuals and organizations: users, customers, marketing personnel, requirements writers, designers, testers, managers, and others. The document must be written in a manner that enables all these people to fully appreciate the system needed and being built so that there are no surprises.

Creation of multiple requirements specifications (each for a subset of the stakeholders) works only if you can guarantee consistency across the versions. A more effective method is to maintain the natural language (Augment, Never Replace, Natural Language) while incorporating multiple views of a more formal nature (Use Multiple Views of Requirements and Reduce Ambiguity in Requirements).

I want to stress the importance of keeping requirements specifications consistent. Many teams find it helpful to use a wiki, such as Confluence, to keep an easy to read and unified version of the requirements specification while using a ticket system, such as JIRA, to document the stories and technical tasks. If these two systems are not kept consistent then the project becomes much more difficult and understanding is lost.


Reference:
Davis, A., "Software Requirements: Objects, Functions, and States," Prentice Hall, Englewood Cliffs, 1993.

Use The Right Techniques

No requirements technique works for all applications. The requirements for complex applications can be best understood when multiple techniques are used. Use a technique or set of techniques most appropriate for your application.

For example, use entity-relation diagrams for data-intensive applications, finite state machines or statecharts for reactive (real-time) systems, Petri nets for applications with synchrony challenges, decision tables for decision-intensive applications, and so on.


Reference:
Davis, A., "A Comparison of Techniques for the Specification of External System Behavior," Communications of the ACM, September 1988.

Avoid Design in Requirements

The purpose of a software requirements specification (SRS) is to specify external behavior of the product. It should be specific enough that all stakeholders reach the same conclusion about the product's intended behavior. A different document created by a designer will specify a software architecture and/or algorithms.

If requirements writers (product managers) find it difficult to specify external behavior unambiguously without resorting to design, then a disclaimer should be included:

Warning: The "design" contained herein is supplied as an aid in understanding the product's external behavior only. The designer(s) may select any design they wish provided it behaves externally in a manner identical to the external behavior of the above system.

This is a good reminder to both the product manager that they are not the designer or architect, and to the designer that selection of optimal architectures and algorithms is their responsibility.


Reference:
Davis, A., Software Requirements: Objects, Functions, and States, Prentice Hall, 1993.

Review The Requirements

A formal review of the Software Requirements Specification (SRS) should be conducted prior to a major investment in the design or code. All of the many parties that have a stake in the success of a product should be involved in the review: users, marketing personnel, developers, testers, and so on. Everyone should be contributing to the correctness and completeness of the SRS.

Barry Boehm provides some advice on how to go about reviewing a SRS. In short, you want to determine if it is:

• complete
• consistent
• feasible
• testable

Related software development principles that can help with the SRS:

• Know Formal Methods
• Augment, Never Replace, Natural Language
• Write Natural Language Before a More Formal Model

Reference:
Boehm, B., "Verifying and Validating Software Requirements and Design Specifications," IEEE Software, January 1984.

Microservices

A well written article about microservices that doesn't subscribe to the buzz.

https://www.dwmkerr.com/the-death-of-microservice-madness-in-2018/

Identify Subsets

When writing a requirements specification it is important to clearly identify the minimal subset of requirements that might be useful. This is also known as identifying the minimum viable product. Now, extend that minimum viable product concept across the timeframe from when development starts and the completion of the product. Identify the minimal increments that might make the minimal subset more and more useful. Such identification provides software designers with insight into optimal software design. It will enable designers to:

1. More easily embed just one function per component.
2. Select architectures that are more contractible and extendable.
3. Understand how to reduce functionality in the case of a schedule or budget crunch.

A very effective technique of recording subsets is to rank the order of a products features by value. Compliment that ranking by grouping features into minimum viable products over the schedule of the product. Take your software requirements specification (SRS) and include columns in the margin beside each requirement. Each column corresponds to a different version of your product. These versions can represent multiple flavors of a product, each tailored to a different customer or situation, or they can represent increasing levels of enhancement through time. In either case, place an "X" in the appropriate columns to indicate which versions will have which features.

Reference:
Parnas, D., "Designing Software for Ease of Extension and Contraction," IEEE Transactions on Software Engineering, March 1979.

Record Why Requirements Were Included

A requirements specification is the culmination of many different activities: debates, discussions, architectural studies, statements of work, etc. So, when someone wants to change a requirement we need to know why that requirement exists - what was the motivation behind that requirement - before we can decide if it is safe to change it. Similarly, when a system fails to satisfy a requirement, we need to know the background of the requirement before we can decide if we should modify the system to meet it or modify the requirement to match the system. If your agile team is not giving any such consideration to missed acceptance criteria then your agile team needs to include the person writing the acceptance criteria.

When a requirements decision is made about an acceptance criteria, record a pointer to its origin. For example, if the decision was made during an interview with a customer, record the day and time, as well as the participants in the interview. It is only with such documentation that you can

1. evolve requirements later or
2. respond to situations where the as-built system fails to satisfy the requirements.

Reference:
Gilb, T., Principles of Software Engineering Management, Reading, MA.: Addison-Wesley, 1988.

Prototypes Reduce Risk In Selecting User Interfaces

To reach an agreement on a user interface prior to full-scale development, a prototype is your best choice for a low-risk, high-payoff approach. The simplest of prototypes would be a series of screen displays. These so-called "storyboards" give the users the impression of a real system. Not only do they help nail down requirements, they also win the hearts of the customers and users.


Reference:
Andriole, S., "Storyboard Prototyping for Requirements Verification," Large Scale Systems, 1987.

Determine The Requirements Now

Requirements are hard to understand and harder to specify. The wrong solution to this problem is to do a slipshod job of requirements specification, and rush ahead to design and code in the vain hope that:

1. Any system is better than no system.
2. The requirements will work themselves out sooner or later.
3. Or the designers will figure out what can be built as they are building it.

The right solution is to do whatever it takes to learn as many of the requirements as possible now.

• Do prototyping.
• Talk with more customers.
• Work with a customer to get to know his or her job firsthand.
• Collect data.
• Do whatever it takes.

Now document the requirements that you understand and plan to build a system to meet those requirements. If you expect requirements to change significantly, that's okay; plan to build incrementally (Grow Systems Incrementally), but that is no excuse for doing a poor job of requirements specification on any one increment.

Reference:
Boehm, B., "Verifying and Validating Software Requirements and Design Specifications, IEEE Software, January 1984.

Determine The Problem Before Writing Requirements

When faced with what they believe is a problem, many engineers rush into offering solutions. I am guilty of this myself - finding solutions and designing systems is an enjoyable activity. However, problems are often elusive. To properly define the problem:

1. Explore all alternative options for who really has the problem and what the problem really is.
2. Create several solutions for the perceived problem then explore the range of costs, risks, and time delay associated with each solution. While gathering these details you'll likely discover who really has the problem and why the problem really is.
• When solving the problem, don't be blinded by the potential excitement of the first solution.

"Procedural changes are always less expensive than system construction."

Reference:
Gause, D., and G. Weinberg, Are Your Lights On?, New York: Dorset House, 1990.

Poor Requirements Yield Poor Cost Estimates

Poor cost estimation can be traced back to these top five causes that all relate to the requirements process:

1. Frequent requirements changes
2. Missing requirements
3. Insufficient communication with users
4. Poor specification of requirements
5. Insufficient analysis

Here are some ways to improve your requirements process:

• Use prototyping to reduce the risk of incorrect requirements.
• Use configuration management to control change.
• Plan new requirements for future releases.
• Use more formal approaches for requirements analysis and specification.

Reference:
Lederer, A. and J. Prasad, "Nine Management Guidelines for Better Cost Estimating," Communications of the ACM, February 1992.

Take Responsibility

In all the [licensed] engineering disciples, when a design fails, the engineers are blamed. Thus, when a bridge collapses, we ask, "What did the engineers do wrong?" When software fails, the engineers are rarely blamed. If they are, the engineers respond with, "The error always existed. My change just exposed it," or "I was just following the pattern," or "My manager made me do it," or " The schedule left insufficient time to do it right." The fact is that the best methods can be utilized in any engineering discipline to produce awful designs. And the most antiquated methods can be utilized in any engineering discipline to produce elegant designs.

There are no excuses. If you are the developer of a system, it is your responsibility to do it right. Take that responsibility. Do it right, or don't do it at all.


Reference:
Hoare, C.A.R., "Software Engineering: A Keynote Address," IEEE 3rd International Conference on Software Engineering, 1978.

Research-Then-Transfer Doesn't Work

The achievements of software engineering research laboratories have difficulties making it into practice. Some reasons would be:

1. Software researchers have little experience developing real systems.
2. Solving a technical problem is easier than making sure it fits in a real system.
3. Researchers and practitioners have different vocabularies which results in difficult communication.

To best improve the chances of successful transfers, you need to from close ties between research and practice in the beginning. Use the industrial environment as the laboratory in which to germinate ideas. Don't try to formulate an idea then transfer it into industry.

Reference:
Basili, V., and J. Musa, "The Future Engineering of Software: A Management Perspective," IEEE Computer, Sept 1991.

Use The Same Name For The Same Concept

Technical documentation must always use the same words to refer to the same concept and the same sentence structure for similar messages. To do otherwise could confuse the reader, causing the reader to spend time trying to determine if there was a technical message in the rewording itself.

For example,

There are three types of special commands. Regular commands come in four varieties.

is not as good as:

There are three types of special commands. There are four types of regular commands.

Reference:
Meyer, B., "On Formalism in Specifications," IEEE Software, January 1985.

Every Software Document Needs An Index

An index is a list of all terms and concepts used in the document, together with one or more page numbers where the term or concept is defined, used, or referenced. This is useful for requirements, design, test cases, and maintenance documents. The index is essential to finding information quickly and during maintenance.

Every Document Needs A Glossary

It is a frustrating experience to read a document and come across a term that is not familiar. The frustration is short-lived; however, when a glossary is available.

The definitions of all terms should be written in a manner that minimizes the need to use the glossary. One technique is first to explain the term in common, everyday terminology, and then add a second definition that uses other glossary terms. Terms used within definitions that are themselves defined elsewhere should be italicized.

Use Documentation Standards

If your project requires that a documentation standard be followed, then, of course, follow it. However, never blame a standard for doing a bad job. Standards exist to provide organizational and content guidance.

Innovate! Follow the standard and do it intelligently. That means including what you know needs to be included regardless of what the standard says. It means writing in clear language. It means adding additional levels of organization that makes sense. If you are not required to follow a standard, at least use one as a checklist to verify that you don't have major omissions.


Reference:
IEEE Computer Society, Software Engineering Standards Collection, Washington, D.C.: IEEE Computer Society Press, 1993.

Don't Ignore Technology

Software engineering technology is evolving rapidly. You cannot afford to sit around without keeping abreast of new developments. Software engineering appears to grow by waves. Each wave brings with it a large collection of fads and buzzwords. Although each wave appears to last just five to seven years, the wave does not simply disappear. Instead each subsequent wave stands upon the best features of all previous waves. (Hopefully "best" means "most effective," but unfortunately it often means "most popular.")

I know of two ways to keep abreast of the technology: reading the right magazines (and books - if very recently published) and talking to the right people. IEEE Software and Communications of the ACM magazines are a good place to learn about what's likely to be useful in the zero-to-five-year timeframe. To learn from talking to people, you must meet the right people. Although talking to folks in your own organization is necessary, it isn't sufficient. Try attending one or two key conferences per year. The presentations are probably not as important as the conversations you have in the hallways.


Reference:
Meyer, B., "On Formalism in Specifications," IEEE Software, January 1985.

Follow The Lemmings With Care

"If 50 million people say a foolish thing, it is still a foolish thing."
-- Anatole France

Just because many (perhaps even, most) people are doing something does not make it right for you. It may be right, but you need to carefully assess its applicability to your environment. Some examples are:

• object-orientation, software measurement
• You Can Optimize Whatever You Want*
• Collect Data Unobtrusively*
• Know Before You Count*
• Collect Productivity Data*
• Don't Forget Team Productivity*
• software reuse
• You Can Reuse Without a Big Investment
• process maturity
• Use an Appropriate Process Model
• computer-aided software engineering (CASE)
• Technique Before Tools
• Use Tools, but Be Realistic
• Give Software Tools to Good Engineers
• Tools Are Expensive
• prototyping
• Build the Right Kind of Prototype
• Build the Right Features into a Prototype
• Build Throwaway Prototypes Quickly
• Prototypes Reduce Risk in Selecting User Interfaces

In all cases, these offer very positive opportunities for increased quality, decreased cost, or increased user satisfaction. However, the advantages are available only to those organizations in which it makes sense. Although the rewards are significant, their potentials are often oversold and are by no means guaranteed or universal.

When you learn about a "new" technology, don't readily accept the inevitable hype* associated with it. Read carefully. Be realistic with respect to payoffs and risks. Run experiments before making major commitments. But by no means can you afford to ignore "new" technologies (Don't Ignore Technology).

Reference:
Davis, A., "Software Lemmingineering," IEEE Software, September 1993.

Fast Software Performance

Here are some aspects of software development that should be considered when trying to improve an application's performance.

Write Better Algorithms

Ultimately, the performance of an application is based on how well is is written. If the program loops around all elements in an array, the JVM will optimize the array bounds-checking so that the loop runs faster, and it may unroll the loop operations to provide an additional speedup. But if the purpose of the loop is to find a specific item, no optimization in the world is going to make the array-based code as fast as a different version that uses a HashMap.

A good algorithm is the most important thing when it comes to fast performance.

Improving your Algorithms & Data Structure Skills | medium

Write Less Code

A small well-written program will run faster than a large well-written program. This is true in general of all programs, and it applies specifically to Java programs. The more code that has to be compiled, the longer it will take until that code runs quickly. The more objects that have to be allocated and deallocated, the more work the garbage collector will have to do. If the objects are allocated and retained, the longer a garbage collection cycle will take. The more classes that have to be loaded from disk in the JVM, the longer it will take for a program to start. The more code that is executed, the less likely it will fit in the hardware caches on the computer. And the more code that has to be executed, the longer it will take.

More code / more features is a "Death by a thousand cuts". A developer will add a very small check for a feature then other developers will do the same and suddenly the performance has regressed. The cycle is repeated in the next release, and the performance starts to be noticeable. A couple of times during the process, performance testing might hit some resource threshold - a critical point in memory use, or a code cache overflow, etc. In those cases, the regular performance tests might make it possible to fix what appears to be a major regression. But over time, as the small regressions creep in, it will be harder and harder to fix.

I'm not advocating that you never add new features or code. The benefits of enhancing your applications is clear. But be aware of the small trade-offs you are making.

Writing Less Damn Code | heydonworks
Write Less Code | codeahoy
The Best Code Is No Code At All | codinghorror

Optimization Best Practices

Software engineers are expected to be familiar with the coding constructs that are known to be bad for performance. When writing code it is not "premature optimization" to apply your knowledge of best practices. So long as you are able to write clean, straightforward code that is simple to read and understand then you don't need to worry that you are prematurely optimizing your code.

30 Java Programming Tips and Best Practices for Beginners | javacodegeeks

Look Elsewhere

If you are developing standalone applications that use no external resources, then the performance of that application is mostly all that matters. Once an external resource such as a database is added, then the performance of both programs is important. And in a distributed environment, say an application server, a load balancer, a database, and more, then the performance of the single application server might be the least of the performance issues. In such an environment, a structured approach must be taken towards all aspects of the system. CPU usage, I/O latencies, and throughput of all parts of the system must be measured and analyzed; only then can it be determined which component is causing the performance bottleneck.

Optimize for the Common Case

It is tempting to treat all performance aspects as equally important. But focus should be given to the common use case scenarios.

• Optimize code by profiling it with realistic usage and focusing on the operations taking the most time.
• Apply Occam's razor to diagnosing performance problems. The simplest explanation for a performance issue is the most conceivable cause; a performance bug in new code is more likely than a bug in the JVM or the operating system.
• Write simple algorithms for the most common operations in the application. In general, optimize for the majority of your users. That will give you good overall performance stats but might not be what you need. For example, if 10% of your users, make 90% of your profit then you should optimize for that 10%.

Finally, JVM Tuning

Now that you have gone through the previous aspects that affect program performance, you are in a good place to tune the JVM. 

Align Reputation With Organization

It is generally recognized that Japanese software engineers view software bugs differently than American software engineers. Although many factors influence this, one relates to the perception in Japan that an error in a product is a disgrace to the company, and a disgrace to the engineer. This works more effectively in Japan than in the United States because Japanese workers tend to remain in one company for their entire careers. The mind-set, however, is important regardless of employment longevity.

In general, when anybody finds an error in a software engineer's product, that engineer should be thankful, not defensive. To err is human. To accept, divine! When an engineering error is found, the person causing it should broadcast it, not hide it. The broadcasting has two effects:

1. It helps other engineers avoid the same error.
2. It sets the stage for future non-defensive error repair.

Consider some guidelines for reporting errors.

1. Ask a coworker to check your work. Someone who will give you time to contact the author and won't judge you if you are wrong.
2. Give the author time to verify your report of an error.
3. Discuss with the author how to best report the error so that the error gets fixed with as little drama as possible and so the right people are informed.

Reference:
Mizuno, Y., "Software Quality Improvement," IEEE Computer, March 1983.

Know Formal Methods

Formal methods are not easy without strong discrete mathematical skills. On the other hand, their use (even on the back of an envelope) can aid significantly in uncovering problems in many aspects of software development. At least one person on every project should be comfortable with formal methods to ensure that opportunities to building quality into the product are not lost. And that requirements are properly understood.

Many people think that the only way to use formal methods is to specify a system completely using them. This is not true. In fact, one of the most effective methods is to write a natural language specification first. Then attempt to write parts using formal methods. Just trying to write things more formally will help you find problems in the natural language. Fix the natural language and you now have a better document. Discard the formalism if desired after it has helped you.

Reference:
Hall, A., "Seven Myths of Formal Methods," IEEE Software, September 1990.