looking for help to translate a sketch so that non-programmers understand it

Using Arduino Programming Questions
#1

As the topics refers to am i in need of help to translate a code so that people who doesn’t know how to program can understand it.
I haven’t used the normal // to write what it means because this is for a seperate document.
The code is the following:

#include <SPI.h>
It’s a Arduino library for communicating with devices using the Serial Peripheral Interface (SPI) Bus.
Serial Peripheral Interface (SPI) is a synchronous serial data protocol used by microcontrollers for communicating with one or more peripheral devices quickly over short distances. It can also be used for communication between two microcontrollers. (Arduino, n.d.)
#include <Ethernet.h>
With the Arduino Ethernet Shield, this library allows an Arduino board to connect to the internet. It can serve as either a server accepting incoming connections or a client making outgoing ones. The library supports up to four concurrent connection (incoming or outgoing or a combination). (Arduino, n.d.)
byte mac[] = { 0x90, 0xA2, 0xDA, 0x0D, 0xB7, 0xD9 };
The Media access control (mac) address is setup so that it is possible to lock the Arduino for a certain IP address on the network. The mac address is printed on the back of the Ethernet shield.
IPAddress serverIP(192,168,1,45);
The IP address is setup so that it is possible to establish a TCP connection.  The Arduino can obtain its own IP address but when you need to connect to it and forward a port for it on the router you need to be sure which IP address it got therefore is it a good idea to set it up. 
byte gateway[] = { 192, 168, 1, 1 }; 
It’s the internet access via the router
byte subnet[] = { 255, 255, 255, 0 }; 

EthernetServer server(5190); 
The specified port the server is going to listen on for a connect request. 
int led = 8;
Pin 8 on the Arduino Ethernet is called led. When working with a lot of different pins it can be a good idea to give them names so that it’s easier to remember which task they have. For this prototype the researcher started with testing the code with a LED bulb hence the name.
void setup()
The part which will run once every time the Arduino is turned on. 
{
This is used to mark blocks of code and it need to be in the beginning and ending of the blocks.
pinMode(led, OUTPUT);
Setting up the pin as output.
Ethernet.begin(mac, serverIP, gateway, subnet);
Initialize the Ethernet device
server.begin();
Start listening for clients
}
Ends the block of code in the void setup
void loop()
The code which is going to run in circuits as long as the Arduino is turned on. 
{
This is used to mark blocks of code and it need to be in the beginning and ending of the blocks.
EthernetClient client = server.available();
This piece wait makes it wait for a client to connect and will only run the next part of the code if a client connect.
if (client) {
If a client connect it will continue.
char inBuffer[32];
This code load the data into a buffer called inBuffer. The maximum size of the buffer is set to 32 bytes.  
int inCount = 0;

while (client.connected()) {
While the client is connected it will do the following
while (client.available()) {
If there is any data received from the client it will continue.
char ch = client.read();
The Arduino reads the client is sending to it.
if(inCount < 31 && ch != '\r' && ch != '\n') {

inBuffer[inCount] = ch;

inCount++;

inBuffer[inCount] = 0;

}
}
The } above is just the ends of the earlier written code pieces. 
if(strcmp(inBuffer,"on") == 0) 

digitalWrite(led, HIGH), 
It switches the power on. 
client.println("The power is ON");
It writes to the client that the power is on.
else if(strcmp(inBuffer,"off") == 0) 

digitalWrite(led, LOW), 
It switches the power off.
client.println("The power is OFF");
It writes to the client that the power is off.
else client.println("Wrong Commando");
If it receive other characters then on and off it will tell the client that it’s a wrong commando.
if(inCount > 0) {
If the data is bigger than 0 bytes it do the following
client.println("Closing connection");
It tells the client that the connection is going to close. The text inside the “” is just a random message which can be change to anything.
delay(2000);
A delay before it proceed to the next command. The delay is for 2 seconds but because the Arduino calculates in milliseconds it has to be 2000. 
client.stop(); 
It closes the connection to 
}
}
}
}
The } above is just the ends of the earlier written code pieces.

And as you can see is there some spots where im not sure about how to explain it.
it is the following code there is troubling me:

byte subnet[] = { 255, 255, 255, 0 }; 
int inCount = 0;
if(inCount < 31 && ch != '\r' && ch != '\n') {
inBuffer[inCount] = ch;
inCount++;
inBuffer[inCount] = 0;
if(strcmp(inBuffer,"on") == 0) 
else if(strcmp(inBuffer,"off") == 0)

I hope someone is up for the challenge and wants to help me with this and if you see some corrections in the translation i have already done don’t hesitate to correct me.

thanks in advance :slight_smile:

#2

I haven't used the normal // to write what it means because this is for a seperate document.

I'd leave proper comments in the source, so it can be followed, and compiled with a simple cut-and-paste.
Your separate document could remove them with a simple search and replace.

#3

AWOL:

I haven't used the normal // to write what it means because this is for a seperate document.

I'd leave proper comments in the source, so it can be followed, and compiled with a simple cut-and-paste.
Your separate document could remove them with a simple search and replace.

that was a good idea.. thank you.. but i still need to get the last bits explained and im not sure how to do that

#4 
int inCount = 0;
if(inCount < 31 && ch != '\r' && ch != '\n') {
inBuffer[inCount] = ch;
inCount++;
inBuffer[inCount] = 0;

This part is declaring an index into an array, checking that the index is still in bounds, using it to store a character in the array, incrementing it, and then using it to store a NULL in the array.

#5

In other words, it is building a C string, character by character.

#6

And please add enough white lines between logical blocks/steps of code …
and indenting the code to show the structure of the sketch. → that is a sort of “body language” for code :wink:

#7

What sort of people are going to read your explanations?

The explanations in your first post would be very helpful to someone who understands programming but might not know about the Arduino.

However they literally wouldn't mean a thing to a couple of my best friends who have no interest in computing even though they are quite practical at DIY. What's more they would have no interest to try to understand.

For example the first few words "It’s a Arduino library for communicating with devices" assume a huge amount of knowledge on the part of the reader. Consider that the normal meaning of a library is a building that contains books. And "communicating with devices" would just be gobbledegook unless you already know what it means. In reality those words are the professional jargon of the programming industry just as "habeas corpus" is the jargon of the legal profession.

Do you want to explain what the program does? - which would be best done without any reference to the code.
Do you want to teach people how the program does what it does? - in which case you first need to understand (or envisage) how they think it works and then explain it without reference to the code.
Do you want to teach programming - pick a simpler example to start with.

(In my humble opinion)

...R

#8

First of all thanks for all the advices.

PaulS:

int inCount = 0;

if(inCount < 31 && ch != ‘\r’ && ch != ‘\n’) {
inBuffer[inCount] = ch;
inCount++;
inBuffer[inCount] = 0;



This part is declaring an index into an array, checking that the index is still in bounds, using it to store a character in the array, incrementing it, and then using it to store a NULL in the array.

Thank you… if you should explain this for a newbie in programming how will you do that? maybe by using an metaphor

Robin2:
What sort of people are going to read your explanations?

The explanations in your first post would be very helpful to someone who understands programming but might not know about the Arduino.

However they literally wouldn’t mean a thing to a couple of my best friends who have no interest in computing even though they are quite practical at DIY. What’s more they would have no interest to try to understand.

For example the first few words “It’s a Arduino library for communicating with devices” assume a huge amount of knowledge on the part of the reader. Consider that the normal meaning of a library is a building that contains books. And “communicating with devices” would just be gobbledegook unless you already know what it means. In reality those words are the professional jargon of the programming industry just as “habeas corpus” is the jargon of the legal profession.

Do you want to explain what the program does? - which would be best done without any reference to the code.
Do you want to teach people how the program does what it does? - in which case you first need to understand (or envisage) how they think it works and then explain it without reference to the code.
Do you want to teach programming - pick a simpler example to start with.

(In my humble opinion)

…R

i would like to explain what the program(sketch) does step by step so that people who doesn’t know how to program can understand it

#9

i would like to explain what the program(sketch) does step by step so that people who know how to program can understand it

I know how to program. I already understand what the code does, without needing your comment book.

I think you need to reconsider your target audience.

#10

Malibux:
i would like to explain what the program(sketch) does step by step so that people who doesn’t know how to program can understand it

Try something like this:
#include <SPI.h>
This tells the compiler to include the library file, SPI.h, when it compiles the sketch. The SPI.h file contains instructions on how the Serial Peripheral Interface (SPI) is to be operated. SPI is a synchronous serial data protocol used by microcontrollers for communicating with one or more peripheral devices quickly over short distances. It can also be used for communication between two or more microcontrollers…

#11

I think that you are fighting a losing battle if the explanation of the code contains any words that depend on other knowledge. Take the previous post as an example.

compiler
library file
sketch
Serial
Peripheral
Interface
microcontrollers

All of these assume prior knowledge or (yet more) explanation.

#12

It's been tried before, called Cobol. It was supposed to be readable by management, as it had easy-to-follow terms like:

ADD CURRENT-SALARY TO TOTAL-SALARY.

Well-intentioned though it was, at the end of the day, programming code needs to be looked at by people with some programming experience.

Implicit in the code is the following fact: the code proceeds linearly (until it hits a looping instruction).

I once taught someone who couldn't see the problem in this code:

print (a)
a = b + c
b = 5
c = 3

The problem was, the instructions are in the wrong order. Try explaining that! As far as this person was concerned all elements of the problem were fully explained, and the order was irrelevant.

#13

The problem was, the instructions are in the wrong order.

It's worse than that even - try explaining x = x + 1; to a mathematician. :smiley:

#14

okay i can see the problem so maybe i should change the assignment.
The new assignment will be to try explain the sketch for people who know a bit about coding… so how will you explain the following with your own words to a person who know a bit about programming an arduino:

byte subnet[] = { 255, 255, 255, 0 }; 
int inCount = 0;
if(inCount < 31 && ch != '\r' && ch != '\n') {
inBuffer[inCount] = ch;
inCount++;
inBuffer[inCount] = 0;
if(strcmp(inBuffer,"on") == 0) 
else if(strcmp(inBuffer,"off") == 0)
#15

I think that the real issue is that no line of code taken out of context can be adequately explained. A line like:

int inCount = 0;

means nothing by itself.

#16

Malibux:
how will you explain the following with your own words to a person who know a bit about programming an arduino:

Summarise the code to pseudocode which explains what each section of the code aims to do, and then insert that in the code as block comments at the start of each section.

At each significant control point in your code, add a comment that says what circumstances you expect to be in when the code execution reaches this point.

Don't try to explain what each line of code does. What is much more useful is to explain why it does it.

The familiar you can assume your reader is with this programming environment and this problem domain, the easier that will be. Trying to make complex code understandable to a non-programmer is likely to be an exercise in futility.

Make sure you yourself understand what the code does before you start; without that understanding, you're wasting your time trying to explain it to somebody else.

#17

PeterH:

Malibux:
how will you explain the following with your own words to a person who know a bit about programming an arduino:

Summarise the code to pseudocode which explains what each section of the code aims to do, and then insert that in the code as block comments at the start of each section.

At each significant control point in your code, add a comment that says what circumstances you expect to be in when the code execution reaches this point.

Don’t try to explain what each line of code does. What is much more useful is to explain why it does it.

The familiar you can assume your reader is with this programming environment and this problem domain, the easier that will be. Trying to make complex code understandable to a non-programmer is likely to be an exercise in futility.

Make sure you yourself understand what the code does before you start; without that understanding, you’re wasting your time trying to explain it to somebody else.

Okay thanks for the advices… i’ll try it :slight_smile:

#18

Is the intention to teach someone that doesn't know how to program how to program by using an example? Or is it to simply explain to someone what your code does?

I fail to understand why a non-programmer would want or need to look at code in the first place.

Consider this:
Input-Processing-Output

The average person only needs to understand input and output, and how they relate to each other (what input generates what output.) They don't need (nor normally care) what the processing part does. So if that is your intended audience, present it to them only in that way.

#19

Malibux:
First of all thanks for all the advices.

PaulS:

int inCount = 0;

if(inCount < 31 && ch != ‘\r’ && ch != ‘\n’) {
inBuffer[inCount] = ch;
inCount++;
inBuffer[inCount] = 0;



This part is declaring an index into an array, checking that the index is still in bounds, using it to store a character in the array, incrementing it, and then using it to store a NULL in the array.

Thank you… if you should explain this for a newbie in programming how will you do that? maybe by using an metaphor

Exactly how AWOL described it:

AWOL:
In other words, it is building a C string, character by character.

If you are trying to teach a non-programmer how to program, the best way is to break things down in terms of function. And then explain it to them in terms they understand and give examples of ordinary things.

For example, programming is pretty much like a recipe. There is the setup and preparation, and then the actual steps. Ingredients would be like variables, pin definitions, constants, etc…

Interrupts are like the phone ringing or an alarm going off, etc…

Get them to think about how they go through the day. They have a series of sequential steps which are varied by inputs. Tests (If, Switch, While) are like checking the temperature of water before adding the pasta.

You get the idea…

#20

If have now tried to redo some of the explaination of the code by using yours advices. Now i would like to hear if the explainations make sence to you and what you think of the explainations.

Thanks in advance

#include <SPI.h>
It’s an Arduino library (Library, 2012) for communicating with devices using the Serial Peripheral Interface (SPI) Bus.
“Serial Peripheral Interface (SPI) is a synchronous serial data protocol used by microcontrollers for communicating with one or more peripheral devices quickly over short distances. It can also be used for communication between two microcontrollers.” (SPI, 2013)

#include <Ethernet.h>
“With the Arduino Ethernet Shield, this library allows an Arduino board to connect to the internet. It can serve as either a server accepting incoming connections or a client making outgoing ones. The library supports up to four concurrent connection (incoming or outgoing or a combination).”

byte mac[] = { 0x90, 0xA2, 0xDA, 0x0D, 0xB7, 0xD9 };
The Media access control (Mac) address is setup as an ID for the Arduino Ethernet. This makes it possible for the router to recognize the Arduino and thereby is it possible the Arduino for to get a certain IP address on the network. The Mac address is printed on the back of the Ethernet shield.

IPAddress serverIP(192,168,1,45);
The IP address is setup so that it is possible to establish a TCP connection.  The Arduino can obtain its own IP address but when you need to connect to it and forward a port on the router you need to be sure which IP address the Arduino Ethernet got, therefore is it a good idea to set it up. 

byte gateway[] = { 192, 168, 1, 1 }; 
It’s the internet access via the router

byte subnet[] = { 255, 255, 255, 0 }; 
Is defining how many IP addresses there are on the network. On this network there 254.

EthernetServer server(5190); 
The specified port the server is going to listen on for a connect request. 

int led = 8;
Pin 8 on the Arduino Ethernet is named led. When working with a lot of different pins it can be a good idea to give them names so that it is easier to remember which task they have. For this prototype the researcher started with testing the code with a LED bulb hence the name.

void setup()
The part which will run once every time the Arduino is turned on. 

{
This is used to mark blocks of code and it need to be in the beginning and ending of the blocks.

pinMode(led, OUTPUT);
Ethernet.begin(mac, serverIP, gateway, subnet);
server.begin();
Setting up the pin as output and Initialize the Ethernet device. When the setup is done is the Arduino listening for clients to connect.

}
Ends the block of code in the void setup

void loop()
This indicates the beginning of the Loop which is going to run in circuits as long as the Arduino is turned on. 
{
Begin of the Loop

EthernetClient client = server.available();
if (client) {
This piece makes it wait for a client to connect and will only run the next part of the code if a client connect.

char inBuffer[32];
This code loads the data into a buffer called inBuffer. The maximum size of the buffer is set to 32 bytes.  

int inCount = 0;
This part is declaring an index into an array.

while (client.connected()) {
while (client.available()) {
While the client is connect the following should be done. 

char ch = client.read();
This parts make sure that Arduino reads what there is send to it.

if(inCount < 31 && ch != '\r' && ch != '\n') {
inBuffer[inCount] = ch;
inCount++;
inBuffer[inCount] = 0;
This part is removing the carriage return and line feed, checking that the index is still in bounds,  incrementing it, and then using it to store a NULL in the array.

}
}
The } above is just the ends of the earlier written code pieces. 

if(strcmp(inBuffer,"on") == 0) 
This part is where the data is compared with the command that the Arduino should react on. The Arduino should only react on when it receives the character on. If the Arduino receives the command on it will proceed with the following. 

digitalWrite(led, HIGH), 
It switches the power on. 

client.println("The power is ON");
It writes to the client that the power is on.

else if(strcmp(inBuffer,"off") == 0) 
Again a part where the data is compared with the command that the Arduino should react on. If the Arduino receive the command off it will do the following.  

digitalWrite(led, LOW), 
It switches the power off.

client.println("The power is OFF");
It writes to the client that the power is off.

else client.println("Wrong Commando");
If the Arduino receive any other characters then on and off it will tell the client that it is a wrong commando.

if(inCount > 0) {
If the data received is bigger than 0 bytes it will proceed with the following.

client.println("Closing connection");
It tells the client that the connection is going to close. The text inside the “” is just a random message which can be change to anything.
delay(2000);
A delay before it proceed to the next command. The delay is for 2 seconds but because the Arduino calculates in milliseconds it has to be 2000. 

client.stop(); 
It closes the connection to 

}
}
}
}
The } above is just the ends of the earlier written code pieces.