Software Architecture and Code Quality Introduction

Background and Purpose
- The Computer Science Student Society (CS cubed) has existed since approximately $2013$ .
- It serves students in computer science, data science, design, and mathematics, as well as anyone interested in those fields.
- The society functions as a social club that also develops students' professional prospects through networking and industry engagement.
Activities and Events
- Student-led and student-decided events include barbecues, games nights, and quiz nights.
- A large annual careers fair is organized to connect students with potential employers.
- An end-of-year pub crawl is a signature social event.
- The society hosts various design competitions.
Industry Importance and Career Benefits
- Modern industry hubs, such as those in Auckland, are becoming more selective, with some firms no longer hiring juniors for basic roles.
- Employers look for candidates who offer value beyond academic achievements, such as experience in networking, event management, and team collaboration.
- Involvement in the society committee provides direct contact with industry through organizing sponsors, managing finances, and facilitating career fairs.
- The committee commitment involves approximately $30$ minutes per week on average, primarily for meetings.

Definition and Scope
- Software architecture refers to the structure of a system, the methods for creating those structures, and the organization of how various components fit together.
- As software grows in size and complexity, significant effort must be placed into design to avoid structural issues.
- Architecture is a high-paying role because it involves taking responsibility for high-level system integrity.
Software Engineering Umbrella
- Software engineering is a high-level discipline encompassing architecture, code quality, version control, team dynamics, development methods, and software development life cycles.
- Architecture is often identified by the consequences of its absence or failure; a common industry sentiment is and "You may not know what it is, but you know when you get it wrong."
Course Prerequisites
- A strong understanding of Object-Oriented Programming (OOP) concepts is required.
- Practical proficiency in either Java or C Sharp is expected.

Scale of Software in Industry
- While university assignments may consist of approximately $500$ lines of code, industry projects are significantly larger:
  - Military drones: $3,500,000$ lines of code.
  - Boeing aircraft: $6,500,000$ lines of code.
  - Google Chrome: $6,700,000$ lines of code.
  - Combined Google services: $2,000,000,000$ lines of code.
- Large-scale projects increase the likelihood of small errors having massive or hidden impacts.
The Social Contract of Programming
- Industry work is typically done in teams rather than individually.
- Code must be readable and extendable by teammates and external developers using APIs or libraries.
- Naming conventions act as a social contract, ensuring that developers in a specific language (e.g., JavaScript) can understand each other's work through familiar styles.

Naming Conventions
- Names for classes, methods, and variables should be informative and descriptive.
- Good naming allows a developer to understand the purpose of a function without reading the internal logic and makes the codebase searchable.
- Java typically follows CamelCase (e.g., doThing).
Code Structure
- Modularity: Logical grouping of functionality to allow for easy code reuse.
- Refactoring: Regularly cleaning code, specifically to remove "magic numbers" and "magic strings."
- Styling: Proper indentation and white space management. This is often enforced by a "linter," a tool built into the Integrated Development Environment (IDE) that follows a set of style rules.
- Consistency: Adhering to the specific "house style" or coding conventions of an organization.
Magic Numbers and Strings
- These are hard-coded values (e.g., the number $42$ or the string "test") used without context.
- They are volatile and prone to causing breaks.
- If a specific number is required for a known reason, it should be accompanied by a comment explaining that reason.

Informative vs. Redundant
- Comments should provide context and explain why something is happening, rather than just what the code is doing.
- Bad Example: if (number == 1) return 1; // return 1 if true.
- Good Example: // The Fibonacci sequence starts with the values 1, 1.
Audience and Balance
- The audience for comments is other developers; it is assumed they understand the programming language.
- Excessive commenting (every line) is considered poor practice, as is a total lack of comments.
- Ideally, code should have strong method-level and class-level comments that explain the general purpose, reducing the need for line-by-line comments.
Comments in XML
- In Android development, XML comments are used to group sections of layout code and explain specific design choices or attribute structures.

Documentation Types
- Architectural Design Documentation: High-level system structure.
- Technical Documentation: Deep dives into implementation for developers.
- User Documentation: Guides for clients or end-users who may lack a technical background.
Javadoc Utility
- Javadoc allows developers to write comments in a specific format in Java that can be automatically converted into a structured website.
- Syntax involves starting a block with /** and ending with */.
- Standard tags include:
  - @param: Describes the parameters/variables the function takes.
  - @return: Explains what the function returns to the caller.

Question: What are four things that contribute to code quality?
Response: Participants identified comments, documentation, code reuse/modularity, and white space management. Other factors include naming conventions and code structures.
Question: Why are naming conventions important?
Response: They allow developers to identify functions and variables quickly by looking at them and help with searchability and general readability.
Question: Are there any issues with declaring a String using new String("test") in Java?
Response: While technically valid because String is a class and not a primitive, the standard and recommended practice is to declare them as literals (e.g., String s = "test").