Proper Documentation

We’re computer science seniors at Worcester State University so that means we should be able to write a full fledged technical documentation for the program we have written am I correct? Yes and no. We were taught the importance of writing documentation and very lightly touched upon what should be included in documentation but after reading ‘Software Documentation Types and Best Practices’ I learned there are actually different types of documentations for different projects.

The image below shows a general guideline for the steps to be taken when it comes to writing a project documentation.

Project-Documentation

We know that the main goal of effective documentation is to ensure that developers and stakeholders are headed in the same direction to accomplish the objectives of the project. The image below is a breakdown of the two main categories of software documentation:

Documentation-Types-1

The author then goes on and describes the different types of documentation:

System documentation represents documents that describe the system itself and its parts. It includes requirements documents, design decisions, architecture descriptions, program source code, and help guides.

User documentation covers manuals that are mainly prepared for end-users of the product and system administrators. User documentation includes tutorials, user guides, troubleshooting manuals, installation, and reference manuals.

Process documentation represents all documents produced during development and maintenance that describe… well, process. The common examples of process-related documents are standards, project documentation, such as project plans, test schedules, reports, meeting notes, or even business correspondence.

All in all I learned that there is not one special or main way to write documentation but there are actually many.

As always, subscribe if you are interested in Computer Science ideas/technologies/topics!

Advertisements

Angular

After finishing our final project I was still curious on many things about angular and how we would use it in future projects if we were to transition over to becoming a front end developer. This blog ‘Why should you learn Angular in 2018?’ by Aman Goel talks about Angular is, the different types, and the advantages.

From what I’ve learned, Angular is a framework that developers use to build applications (a simplified view). Goel talks about the development of angular applications and how it incorporates Typescript along with HTML and CSS. I know I built my project with the latest version of angular when I created it with the @angular-cli/@latest command but apparently there are versions from Angular 1 to Angular 7 and skipping Angular 3.

Some advantages of using Angular is that it supports Single Page Applications which is what we did for our project. A single HTML page that is updated dynamically according to the interaction of the user.

He lists the advantages of using Angular as seen down below:

– Supports Single Page Applications
– Two-way data binding
– Modularity in Angular
– Reduced coding
– Declarative User Interface
– Easy Integration
– Cross Platform

Before reading this blog I did not know how much we learned from doing this project but after reading it, I realized that all of the advantages listed in this blog were used in the process.

As always, subscribe if you are interested in Computer Science ideas/technologies/topics!

Are we now Full-Stack Web Developers?

As you may know, for our end of semester senior project we worked in groups of two in charge of developing a web application that had some sort of functionality. When we were first introduced to this we didn’t know whether to feel scared, nervous, excited or all of the above. What is HTML, CSS, angular, boostrap, etc.? So many things were thrown at us but in the end we made it. We learned all of it and no the question is.. are we full-stack devs? Maybe Eric An can answer that question in his article, ‘What is a full-stack web developer?’

The article begins with a big red T shaped image. The T-shaped model is a concept that describes the abilities/characteristics of an individual where a person has many generalized skills with a specialization in few. The full-stack web developer supposedly knows many technologies but specializes in few which is front-end development and back-end development.

Front-End web development is the presentation of the website which includes HTML and CSS and sometimes JavaScript; pretty much everything that the user sees when clicking a link. The goal is for users to provide a platform for users to interact with. Some other skills may be UE/UI design. For our project we learned the basics of HTML and CSS and I also learned how to use bootstrap to make things much simpler. Front-end development was a success!

Onto the back-end web development.. The creation of data collection processes haunts us to this day. We redefined the definition of struggle when it came to the back-end part of this project. Back-end development is associated with the front-end where as a server is being created to communicate with that the user is trying to do on the front end.

The definition of a Full-stack web developer is an individual who is in charge of performing both front-end and back-end so that all of the technologies put together makes up a website. After reading this article, although we are not experts in front-end/back-end development we could be considered full-stack developers!

As always, subscribe if you are interested in Computer Science ideas/technologies/topics!

How QA Engineers actually test code

CS 443 has taught me many things: how to test code, the different ways to test code, collaboration among peers, what is possible/not possible in Java, mockito, the list goes on. What it has not taught me is how code is actually tested in the field professionally; what should I expect to do or know if I were to shift towards the QA Engineer path?

‘A Day in the Life of a QA Engineer’ by AJ Larson talks about what he does in a professional setting and I compared it to the daily tasks we performed in class and it seems it is not completely opposite. He starts off by comparing software developers to QA engineers and stating that it is not too different; some companies even combine the two into one where you are a dev and a tester. He talks about how the team communicates; telling each other where they are in the project, what their plan is and if they have been encountering any problems. I guess in a way we have been doing that in class.

Onto the more important part of this blog is where he talks about testing ‘stuff’. He spends his time running manual tests and when he encounters a failed test how he goes about it. I learned that communication is key in both school and professional work environment; pretty much anywhere there is teamwork there must be communication.

As always, subscribe if you are interested in Computer Science ideas/technologies/topics!

Mutation Testing

In the final exam, there were a few questions on mutation testing which I was very unfamiliar with so I decided to look into posts/blogs about mutation testing. One interesting blog I came across was written by James White – ‘Mutation Testing – Who will test the tests themselves?’.

The very first sentenced stated “this is aimed at people who are not familiar with mutation testing” and it was all over from there; I had been sucked into the article since I had no idea what mutation testing really was.

White starts off by describing what mutation testing really is and his definition was “Very simply mutation testing is a way of testing the quality of your tests by introducing changes into your code and seeing if your test suite detects them”. Very straight forward. He then gives an example written in java and a scenario seen below:

private static final int MARGARINE_WEIGHT = 100;
private static final int COCOA_WEIGHT = 25;
private static final int EGG_COUNT = 2;
private static final int ORANGE_JUICE_VOLUME = 15;

Cake createCake(CakeType cakeType) {
Cake cake = new Cake();
cake.setMargarine(MARGARINE_WEIGHT);
cake.setSugar(MARGARINE_WEIGHT);
cake.setEggs(EGG_COUNT);
if (CakeType.CHOCOLATE.equals(cakeType)) {
cake.setFlour(MARGARINE_WEIGHT - COCOA_WEIGHT);
cake.setCocoa(COCOA_WEIGHT);
} else {
cake.setFlour(MARGARINE_WEIGHT);
if (CakeType.ORANGE.equals(cakeType)) {
cake.setOrangeJuice(ORANGE_JUICE_VOLUME);
}
}
return cake;
}

As well as different test cases:

@Test
public void canCreateVictoriaSponge() {
Cake actual = testee.createCake(CakeType.VICTORIA_SPONGE);
assertEquals(100, actual.getMargarine());
assertEquals(100, actual.getFlour());
assertEquals(100, actual.getSugar());
assertEquals(2, actual.getEggs());
assertEquals(0, actual.getOrangeJuice());
}

@Test
public void canCreateChocolateCake() {
Cake actual = testee.createCake(CakeType.CHOCOLATE);
assertEquals(100, actual.getMargarine());
assertEquals(25, actual.getCocoa());
assertEquals(100, actual.getSugar());
assertEquals(2, actual.getEggs());
assertEquals(0, actual.getOrangeJuice());
}

@Test
public void canCreateOrangeCake() {
Cake actual = testee.createCake(CakeType.ORANGE);
assertEquals(100, actual.getMargarine());
assertEquals(100, actual.getFlour());
assertEquals(100, actual.getSugar());
assertEquals(2, actual.getEggs());
assertEquals(15, actual.getOrangeJuice());
}

He then shows us the results of his tests as well as his mutation tests. So I learned that mutation testing works on the principle that since the test code is there to ensure that the code works, if mutating a test, at least one test should fail. Mutation killed means all your tests pass and mutation survived indicates that the mutation survived and there is a potential area where a bug could arise.

As always, subscribe if you are interested in Computer Science ideas/technologies/topics!

Importance of Code Review

Towards the end of the semester we were working more intensively in group settings and even increased the number of individuals in our group which required greater collaboration among peers. I recently came across a post ‘Code Review: The Unit of Work should be a Single Commit’ by Paul Hammant. In this blog Hammant talks about the benefits of Code Review and how the end result is significant change in the way the program was written.

Some of the benefits he listed was:

– Two pairs of eyes catch more bugs (which saves hours of debugging if fixed early)
– Enforce coding standards, style guides (keeps overall readability & code quality high)
– Mentoring of new developers (learning from mistakes without breaking stuff)
– Establish trust relationships
– A good alternative to pair programming.

Our last few classes we as a group came across all of these aspects and more. We worked collectively as a team code reviewing some program and found that we listed many similar mistakes. Another important point he makes is that there is only so many times something is modified in review before it is considered ‘done’.

Although Hammant talks about reviewing code over Git and we did ours as a group in person the idea remains the same. Some steps he talked about were to lock a commit for the duration of each review and also how to move forward with which review change when two individuals have different points of view. I found that this article was relatable to our experience.

As always, subscribe if you are interested in Computer Science ideas/technologies/topics!

DRY over DAMP?

Ever since I picked up my first Java book and read through it, one thing always stuck in my mind when it came to writing any program and that is to not repeat yourself when you don’t have to. Leonardo Brito wrote an interesting piece, “Don’t obsess over code DRYness”, and he gave a few good points on why we shouldn’t try to make our code as complex as we can. He starts off by saying that we, as humans, are good at pattern recognition but sometimes we over-do it. He uses the example codes below:
____________________________________________________________________________
# Example 1
class Car
include Checkups

def maintenance_10k
check_break_fluid
check_battery_terminals
check_engine_oil
end

def maintenance_30k
check_break_fluid
check_battery_terminals
check_engine_oil
check_spare_wheel
end

def maintenance_50k
check_break_fluid
check_battery_terminals
check_engine_oil
check_spare_wheel
check_gearbox
end
end
____________________________________________________________________________
# Example 2
class Car
include Checkups

def maintenance_10k
basic_maintenance
end

def maintenance_30k
basic_maintenance
check_spare_wheel
end

def maintenance_50k
basic_maintenance
check_spare_wheel
check_gearbox
end

private

def basic_maintenance
check_break_fluid
check_battery_terminals
check_engine_oil
end
end
____________________________________________________________________________
After DRYing the code we see that it produces a new method called basic_maintenance while the original maintenance method conveys exactly what the method is expected to do. He then added a change such that we no longer need to check the break fluid on the 10 thousand miles checkup, so now we must remove the method check_break_fluid from basic maintenance and only add it to the upper maintenance methods. What he was trying to illustrate is that although one set of code was easier to read and follow, a simple change could have us altering out code in more ways than we’d like.

Brito talks about the trade off between some duplication over the wrong abstraction because overly DRYing your code could result in more confusion than simply repeating SOME code which is where he introduced another concept: DAMP – descriptive and meaningful phrases. The purpose of these two terminologies is to guide is to write better code and not going to any extremes.

I found that the concept of over DRYing your code interesting because I never thought about it that way and that there was a such thing. I’ve heard of DRY but never DAMP so I found that amusing how they’re opposite from each other. Looking back at my projects I feel as though I stand somewhere in between both concepts. I try to not over-do simplifying yet at the same time I make sure I apply DRY when necessary. I agree with what the author said about repeating sometimes to make it easier on yourself in the end.

Thank you for the read!