theme | _class | paginate | backgroundColor | backgroundImage | footer | headingDivider | marp | style |
---|---|---|---|---|---|---|---|---|
gaia |
lead |
true |
2 |
true |
section {
font-size: 25px;
}
container {
height: 300px;
width: 100%;
display: block;
justify-content: right;
text-align: right;
}
header {
float: right;
}
a {
color: blue;
text-decoration: underline;
background-color: lightgrey;
font-size: 80%;
}
table {
font-size: 22px;
}
div.mermaid { all: unset; }
|
Session 12 Helge Pfeiffer, Associate Professor
The presentation slides of last week's guest lecture are available in our Teams channel.
As announced and as with other material from guest lecturerers, these slides are for you. In case you want to share them with somebody who is not registered in this course, please contact the author and ask for permission.
Next week, guest lecture, Martin Røpcke (NetCompany)
Software engineering @NetCompany
Authentication via GitHub should work without asking for more actions. That is, configure your authentication process so that a user does not need to receive a secret from an email inbox.
Once a user is authenticated to GitHub, she should be able to login to your Chirp!.
I did not reach more... Once I find the time to interact with all your Chirp! applications, I provide feedback
- First hour: Ethics
- Second hour: Documentation
- Third hour: Visual languages for documentation
- Fourth hour: Design, Architecture and project work
[Institute of Electrical and Electronics Engineers] IEEE is the world's largest technical professional organization dedicated to advancing technology for the benefit of humanity. Source: IEEE
[Association for Computing Machinery] ACM, the world's largest educational and scientific computing society, delivers resources that advance computing as a science and a profession. Source: ACM
Source: IEEE Code of EthicsWe, the members of the IEEE, in recognition of the importance of our technologies in affecting the quality of life throughout the world, and in accepting a personal obligation to our profession, its members and the communities we serve, do hereby commit ourselves to the highest ethical and professional conduct and agree:
I. To uphold the highest standards of integrity, responsible behavior, and ethical conduct in professional activities.
II. To treat all persons fairly and with respect, to not engage in harassment or discrimination, and to avoid injuring others.
III. To strive to ensure this code is upheld by colleagues and co-workers.
<style scoped> section { font-size: 23px; } </style>
- GENERAL ETHICAL PRINCIPLES. A computing professional should ... 1.1 Contribute to society and to human well-being, acknowledging that all people are stakeholders in computing. 1.2 Avoid harm. 1.3 Be honest and trustworthy. 1.4 Be fair and take action not to discriminate. 1.5 Respect the work required to produce new ideas, inventions, creative works, and computing artifacts. 1.6 Respect privacy. 1.7 Honor confidentiality. Source: ACM Code of Ethics and Professional Conduct
- PROFESSIONAL RESPONSIBILITIES. A computing professional should ... 2.1 Strive to achieve high quality in both the processes and products of professional work. 2.2 Maintain high standards of professional competence, conduct, and ethical practice. 2.3 Know and respect existing rules pertaining to professional work. 2.4 Accept and provide appropriate professional review. 2.5 Give comprehensive and thorough evaluations of computer systems and their impacts, including analysis of possible risks. 2.6 Perform work only in areas of competence. 2.7 Foster public awareness and understanding of computing, related technologies, and their consequences. 2.8 Access computing and communication resources only when authorized or when compelled by the public good. 2.9 Design and implement systems that are robustly and usably secure. Source: ACM Code of Ethics and Professional Conduct
- PROFESSIONAL LEADERSHIP PRINCIPLES. A computing professional, especially one acting as a leader, should ... 3.1 Ensure that the public good is the central concern during all professional computing work. 3.2 Articulate, encourage acceptance of, and evaluate fulfillment of social responsibilities by members of the organization or group. 3.3 Manage personnel and resources to enhance the quality of working life. 3.4 Articulate, apply, and support policies and processes that reflect the principles of the Code. 3.5 Create opportunities for members of the organization or group to grow as professionals. 3.6 Use care when modifying or retiring systems. 3.7 Recognize and take special care of systems that become integrated into the infrastructure of society. Source: ACM Code of Ethics and Professional Conduct
Read the complete IEEE Code of Ethics
- Soon, you will enter the labor market as a professional software developer. Eventually, many of you will raise in the hierarchy, become team leads, managers, etc. You should be able to look to the mirror and be happy with your actions.
- Image source: Walmart
The Volkswagen emissions scandal [...] began in September 2015, when the United States Environmental Protection Agency (EPA) issued a notice of violation of the Clean Air Act to German automaker Volkswagen Group. The agency had found that Volkswagen had intentionally programmed turbocharged direct injection (TDI) diesel engines to activate their emissions controls only during laboratory emissions testing, which caused the vehicles' NOx output to meet US standards during regulatory testing. However, the vehicles emitted up to 40 times more NOx in real-world driving. Volkswagen deployed this software in about 11 million cars worldwide, including 500,000 in the United States, in model years 2009 through 2015. Source: Wikipedia
Do you want to be the person that implemented that software?
I årevis har Styrelsen for Arbejdsmarked og Rekruttering samt en lang række danske kommuner eksperimenteret med, udviklet og anvendt adskillige forskellige machine learning-modeller, som havde til formål at hjælpe ledige borgere hurtigere i job.
Som Version2 har afdækket, har profileringsprojekterne dog et efter et måttet lukke på grund af både juridiske, tekniske og performancemæssige udfordringer. Særligt juraen har været et problem for kommunerne, siden Datatilsynet i sommeren 2022 offentliggjorde en udtalelse, hvoraf det fremgår, at kommunerne ikke har lovhjemmel til at profilere ledige borgere. Heller ikke selvom borgerne samtykker til profileringen. Source: ING/DataTech
Do you want to be the person that implemented that software?
Total US 2011 video viewing required about 192 PJ of primary energy and emitted about 10.5 billion kg of CO2(e). Shifting all 2011 DVD viewing to video streaming reduces the total primary energy use to about 162 PJ and the CO2(e) emissions to about 8.6 billion kg, representing a savings equivalent to the primary energy used to meet the electricity demand of nearly 200 000 US households each year. Source: A. Shehabi et al. The energy and greenhouse-gas implications of internet video streaming in the United States
Online advertising consumed between 20.38 to 282.75 TWh of energy and 11.53 – 159.93 million tons of CO2e was emitted to produce the electricity consumed [in 2016]. Source: M. Pärssinen et al. Environmental impact assessment of online advertising
Imagine you continue to work on Chirp!. You and your group got hired by a big corporation "LoremIpsumSoft". Chirp! went viral, you have 500 million users from all over the world. Your boss realizes that it is quite difficult to make money with the application, advertisements were tried, but almost all users are blocking them since they are so annoying. Therefore, he comes to you to ask if you could build a statistical model over the users that predicts political positions and believes.He plans to sell the results from such a model to political parties to support their election campaigns
Discuss with your neighbors:
- How do you react?
- What do you answer your boss?
- What do you do yourself?
<style scoped> pre { font-size: 23px; } section { font-size: 23px; } </style>In the 2010s, personal data belonging to millions of Facebook users was collected without their consent by British consulting firm Cambridge Analytica, predominantly to be used for political advertising.
The data was collected through an app called "This Is Your Digital Life", developed by data scientist Aleksandr Kogan and his company Global Science Research in 2013. The app consisted of a series of questions to build psychological profiles on users, and collected the personal data of the users’ Facebook friends via Facebook's Open Graph platform. The app harvested the data of up to 87 million Facebook profiles. Cambridge Analytica used the data to provide analytical assistance to the 2016 presidential campaigns of Ted Cruz and Donald Trump. Source: Wikipedia
/// <summary>
/// This class repesents the user of the _Chirp!_ application.
/// Since _Chirp!_ is a micro-blogging application, all authenticated
/// users are expected to author cheeps.
/// </summary>
public class Author : IdentityUser
{
public List<Cheep> Cheeps { get; set; }
...
}
/// <summary>
/// ...?
/// </summary>
public class Cheep
{
public int Id { get; set; }
public required string Content { get; set; }
public required DateTime Timestamp { get; set; }
...
}
-
Do not over use in-code documentation.
-
Never document trivial or default code!
-
Focus on your domain and complicated business logic.
- Likely you do not have a lot of the latter in Chirp!.
- Where you have it, add respective documentation
-
In code, provide links to sources that influenced your solution.
-
If you create code that is complex and difficult to understand, explain next to it what the reasons for complexity are, what you ruled out as more simple solutions, and everything that the future you/colleague needs to know to understand the reason for complexity.
- Likely you do not have a lot of that in Chirp!.
- You want to document that this is not accidental complexity.
- If you were Skat, you had a lot of inherent complexity.
Provide an explanatory comment for the Cheep
entity class.
/// <summary>
/// ...?
/// </summary>
public class Cheep
{
public int Id { get; set; }
public required string Content { get; set; }
public required DateTime Timestamp { get; set; }
...
}
- End-user documentation
- Developer documentation
- Operator documentation
In your project report, you will provide information for developers and operators, not for end-users. We skip that in this course.
Use inline markup liberally.
Write in short paragraphs.
Use a variety of structural elements. [Lists, tables, code blocks, etc.]
Make your structure visual.
Watch out for passivity.
Omit fluff. Source: Jacob Kaplan-Moss
<style scoped> section { font-size: 18px; } </style>
- Dry sucks
- Before you start, be clear about what you want your reader to do after you end
- Write to a well formed outline, always
- Avoid ambiguous pronouns
- clarity = illustrations + words
- When dealing with concepts… logical illustration and example
- Embrace revision Source: Bob Reselman
Technical documentation is hard, really hard. It's easier to explain what not to do. Some suggestions:
- It's no prose, so don't try to be arty.
- Keep it short!
- When in doubt, drop it.
- Use simple words. Not everyone is fluent in English.
- Any sentence with more then two lines is an anomaly.
- Be consistent. Avoid surprises.
- Use cases and Examples are important and may shorten explanations.
- Include common mistakes and their workarounds.
- You have to refactor often (>>20x).
- Use a versioning system like git or mercurial.
- Avoid abbreviations and introduce them at first occurrence e.g: concurrent versioning system (CVS)
- A column shouldn't exceed 9-12 words (~60 chars) to improve readability.
- Keep your rules in a file (e.g: doc.playbook) and check them
- Let others proof read, or yet better find an editor.
- Try to be gender agnostic. Why? cautionary tale: joyent/libuv#1015 Source: kevin_bauer on Hacker News
... for which you want to have contributors is a bit different though, see e.g., Write the Docs
Image source: Archbee BlogSource: Berkeley Student Learning Center
- Be CONCISE
Don't say: "The mystery lady was one who every eligible man at the ball admired."
Instead say : "Every eligible man at the ball admired the mystery lady."
- Use the VOCABULARY that you know.
Don't always feel you have to use big words. It is always better to be clear and use simple language rather than showing off flashy words you aren't sure about and potentially misusing them. This is not to say, however, that you should settle for very weak vocabulary choices (like "bad" or "big" or "mad").
Read the following paragraph.
Modern software development is full of dependencies on free open source software (FOSS). This software ranges from the application the code is being written in e.i. visual studio code, to how the quality of the software is tested e.i. Moq, NUnit, etc. As such, it is important to keep the health of a project in mind when choosing to rely on it. Source: Anonymous
- Can you understand it?
- Try to improve it.
We take it way more simple. Your project reports are written in one Markdown file and converted to PDF with pandoc
.
There is a plethora of such tools. In this and future courses at ITU, you likely find the following two sufficient.
Many projects consider it a good practice when your illustrations are generated in-code (PlantUML) compared to WYSIWYG editors (DrawIO). (Same philosophy as with markup languages compared, e.g. Microsoft Word files.)
What is Software? Helge's definition:
<style scoped> pre { font-size: 22px; } section { font-size: 22px; } </style>Software is the collection of all artifacts, which allow (a) suitably educated person(s) with access to specified and suitable hardware to instantiate a running system.
Additionally, the collection of such artifacts allow such suitably educated person(s) to understand and reason about a systems' working and properties and let them understand why the system is as it is and why it behaves the way it does. Source: Helge
public class Student
{
public string Name;
public Image photo;
private List<Course> courses;
public Status enroll(Course course)
{
courses.Add(course);
return Status.Sucess;
}
}
public class Manager
{
private List<Student> students;
public void SignUp(string Name, Course course) {
student = students.Where(s -> s.Name == Name).First();
student.enroll(course);
}
}
You saw a quite complex diagram that was inspired by sequence diagrams already earlier. It illustrates the sequence of calls between different systems in OAuth authentication.
Note, sub-system sequence diagrams are more abstract than "normal" sequence diagrams. The former are on the level of (sub-)systems and the latter on the level of objects (in terms of object-orientation).
<style scoped> pre { font-size: 22px; } section { font-size: 22px; } </style>namespace Chirp.CLI.SimpleDB;
public interface IDatabaseRepository<T>
{
public IEnumerable<T> Read(int? limit = null);
public void Store(T record);
}
namespace Chirp.CLI.SimpleDB;
using CsvHelper;
using System.Globalization;
public sealed class CSVDatabase<T> : IDatabaseRepository<T>
{
...
}
A software element that conforms to a standard component model and can be independently deployed and composed without modification according to a composition standard. Source: W.T. Councill et al. "Definition of a Software Component and Its Elements."
A software component is a unit of composition with contractually-specified interfaces and explicit context dependencies only. A software component can be deployed independently and is subject to composition by third parties. Source: C. Szyperski "Component Software: Beyond Object-Oriented Programming"
The component is an independent executable entity that is defined by its interfaces. You don’t need any knowledge of its source code to use it. It can either be referenced as an external service or included directly in a program.
The services offered by a component are made available through an interface, and all interactions are through that interface. The component interface is expressed in terms of parameterized operations, and its internal state is never exposed. Source: I. Sommerville Software Engineering
Discuss with each other, what are components in your Chirp! applications?
- Architecture in the small is concerned with the architecture of individual programs. At this level, we are concerned with the way that an individual program is decomposed into components.
- Architecture in the large is concerned with the architecture of complex enterprise systems that include other systems, programs, and program components. These enterprise systems may be distributed over different computers, which may be owned and managed by different companies. Source: I. Sommerville Software Engineering
@Helge: Name what maps to components in the small and in the large.
[A] Node is a deployment target which represents computational resource upon which artifacts may be deployed for execution. Source: uml-diagrams.org
In your cases, you can consider each service that you receive from Azure as a Node.
use of scientific principles, technical information, and imagination in the definition of a software system to perform pre-specified functions with maximum economy and efficiency Source: ISO/IEC/IEEE 24765:2017 Systems and software engineering-Vocabulary
In every engineering discipline, design encompasses the disciplined approach we use to invent a solution for some problem, thus providing a path from requirements to implementation. In the context of software engineering, Mostow suggests that the purpose of design is to construct a system that:
- Satisfies a given (perhaps informal) functional specification
- Conforms to limitations of the target medium
- Meets implicit or explicit requirements on performance and resource usage
- Satisfies implicit or explicit design criteria on the form of the artifact
- Satisfies restrictions on the design process itself, such as its length or cost, or the tools available for doing the design Source: G. Booch et al. "Object-Oriented Analysis and Design with Applications"
That is similar to what Sommerville says about Software Engineering:
Engineering discipline Engineers make things work. They apply theories, methods, and tools where these are appropriate. However, they use them selectively and always try to discover solutions to problems even when there are no applicable theories and methods. Engineers also recognize that they must work within organizational and financial constraints, and they must look for solutions within these constraints. Source: I.Sommerville "Software Engineering"
The final goal of any engineering activity is the some type of documentation. When a design effort is complete, the design documentation is turned over to the manufacturing team. This is a completely different group with completely different skills from the design team. If the design documents truly represent a complete design, the manufacturing team can proceed to build the product. In fact, they can proceed to build lots of the product, all without any further intervention of the designers. [...] the only software documentation that actually seems to satisfy the criteria of an engineering design is the source code listings. Source: J. Reeves "What is Software?"
Note, other more object-oriented analysis and design advocates have a slightly other opinion on that:
Design involves balancing a set of competing requirements. The products of design are models that enable us to reason about our structures, make trade-offs when requirements conflict, and in general, provide a blueprint for implementation. Source: G. Booch et al. "Object-Oriented Analysis and Design with Applications"
- Read on task of this weeks project work
- Brainstorm with your peers, how you could design such a feature.
- What could be the most simple solution?
- Can you foresee any issues?
Pseudonymization is a data management and de-identification procedure by which personally identifiable information fields within a data record are replaced by one or more artificial identifiers, or pseudonyms. A single pseudonym for each replaced field or collection of replaced fields makes the data record less identifiable while remaining suitable for data analysis and data processing.
[it] is one way to comply with the European Union's new General Data Protection Regulation (GDPR)[ demands for secure data storage of personal information. Pseudonymized data can be restored to its original state with the addition of information which allows individuals to be re-identified. In contrast, anonymization is intended to prevent re-identification of individuals within the dataset. Source: Wikipedia
Architecture represents the set of significant design decisions that shape the form and the function of a system, where significant is measured by cost of change. Source: G. Booch
Architecture is about the important stuff. Whatever that is. On first blush, that sounds trite, but I find it carries a lot of richness. It means that the heart of thinking architecturally about software is to decide what is important, (i.e. what is architectural), and then expend energy on keeping those architectural elements in good condition. For a developer to become an architect, they need to be able to recognize what elements are important, recognizing what elements are likely to result in serious problems should they not be controlled. Source: Martin Fowler "Design - Who needs an architect?"
Combining the concept of the class and object structures together with the five attributes of a complex system (hierarchy, relative primitives [i.e., multiple levels of abstraction], separation of concerns, patterns, and stable intermediate forms), we find that virtually all complex systems take on the same (canonical) form, [...]. Collectively, we speak of the class and object structures of a system as its architecture. Source: G. Booch et al. "Object-Oriented Analysis and Design with Applications"
An illustration of architecture in the large:
Source: Whitepaper om coronapas-appenNext week, guest lecture, Martin Røpcke (NetCompany)
Software engineering @NetCompany on the case of Smittestop
- If not done, complete the Tasks (blue slides) from this class
- Check the reading material
- Work on the project