Ryddighet i kode

[RadiantHeart]

Tenkte jeg skulle høre litt med dere som har erfaring fra litt større programmeringsprosjekter. Hittil når jeg har programmert noe nytt begynner jeg som regel med å programmere litt fort og "gæli", til jeg har fått det til å fungere. Deretter går jeg gjennom og rydder opp, renamer variabler og kommenterer kode.

 

Har hørt mange si at det er lurt å være nøye og ryddig fra starten av når man programmerer større ting. Men er ikke det mye ekstra jobb all den tid koden sikkert må omgjøres kraftig.

 

Hvilken praksis anbefaler dere?

[Goophy]

Hold deg til én kodestandard helt fra første tegn.

Skriver du noe på et par tusen linjer blir det helvete å få oversikt over i ettertid.

 

Kommentarer mens du holder på er også en fordel, fort gjort å glemme hva du tenkte på i ettertid.

Endret 20. mai 2009 av Goophy

[cruzader]

helt enig med goophy, har selv opplevd frustrasjonen det er og måtte skrive deler pånytt fordi koden var laget i hurten og sturten så er et stort kaos uten kommentering eller system så enkleste er bare skrive det på nytt istedenfor nøste opp alt.

[vidarv]

jeg bruker stort sett å få med forklarende variabelnavn på inputvariabler og lokale variabler inne i en metode. Men jeg kan være litt sløv med å gi gode funksjonsnavn og kommentarer i koden, men det fikser jeg ofte etterpå. Det er da ikke så farlig så lenge det er kode under arbeid. Men når koden er ferdig er det ofte lurt å gå over å fylle inn litt kommentarer og dokumentere den før den blir comittet til Trunk (for de som bruker versjonskontroll)

[tickinghd]

Visst man liker å skrive kode i hy og hast så kan man jo vurdere å ta i bruk teknikker for prototyping. Selv forsøker jeg å strukturere ting ordentlig fra starten av, men det kommer ikke uten ulemper fordi spesifikasjonene ofte er ufullstendige. Da kaster man bare bort masse tid. Det er tider for når det lønner seg å være grundig og det er tider når det lønner seg å bli fort ferdig. Jeg tror balansen er noe man oppdager med erfaring.

[JcV]

Tenkte jeg skulle høre litt med dere som har erfaring fra litt større programmeringsprosjekter. Hittil når jeg har programmert noe nytt begynner jeg som regel med å programmere litt fort og "gæli", til jeg har fått det til å fungere. Deretter går jeg gjennom og rydder opp, renamer variabler og kommenterer kode.

 

Har hørt mange si at det er lurt å være nøye og ryddig fra starten av når man programmerer større ting. Men er ikke det mye ekstra jobb all den tid koden sikkert må omgjøres kraftig.

 

Hvilken praksis anbefaler dere?

 

Jeg tror at de som mener at man kan planlegge og konstruere store prosjekter uten å reskrive kode, faktisk ikke har prøvd seg på store ting. Jeg er helt enig at man bør holde seg til en kode standar fra begynnelsen, samme hva den er bare man holder seg til det. Etter vært vil det sitte i fingra og du trenger ikke å tenke så mye på det. Det finnes mange nettsider og bøker om dette temaet, så ta foreksempel en titt på denne siden : http://www.dagbladet.no/development/phpcodingstandard/ .

 

Men alle programmerer som jobber med utvikling, vet at man bør refaktorere koden etter at man har skrevet den. Del opp koder i mindre logiske biter ved hjelp av objekter eller funksjoner. På den måten kan du lett reskrive og teste deler av koden din i etterkant.

 

I forhold til kommentering, føler jeg at det faktisk ikke er så veldig viktig!.. ja dere høret meg .. lol ..

Kommentering inne i kode burde ikke være nødvendig, konsentrer deg heller om å skrive ren kode, mye luft og gode navn på variablene, så vil det være like enkelt å lese koden som å lese kommentarer. Det man kanskje bør kommentere er generelle ting som struktur og avangserte algoritmer som er vannskelig og snurre hode sitt rundt.

Endret 27. mai 2009 av JcV

[Jonas]

Må si meg litt enig med JcV anngående kommenteringen. Hater å se kommentarer for hver bidige linje. Veldig mye er rett og slett svært selvforklarende om man skriver det godt og riktig.

 

<?php

$number[0] = 5; // Define two numbers
$number[1] = 7; // ..

$sum = $number[0] + $number[1]; // Add them together

echo $sum; // Show result

?>

Ovenforstående er utrolig frustrerende å lese.

Endret 27. mai 2009 av Jonas

[Ernie]

I forhold til kommentering, føler jeg at det faktisk ikke er så veldig viktig!.. ja dere høret meg .. lol ..

Kommentering inne i kode burde ikke være nødvendig, konsentrer deg heller om å skrive ren kode, mye luft og gode navn på variablene, så vil det være like enkelt å lese koden som å lese kommentarer. Det man kanskje bør kommentere er generelle ting som struktur og avangserte algoritmer som er vannskelig og snurre hode sitt rundt.

Jeg er forsåvidt enig i det du sier bortsett fra at jeg mener at kommentering er svært viktig, men det må også gjøres riktig. Eksemplet til Jonas viser hvordan det ikke skal gjøres. At kommentering derimot ikke er viktig (underforstått kan unngåes) er tøv, og det tror jeg følgende funksjon er et svært godt bevis på.

 

/**
* Takes an UTF-8 string and returns an array of ints representing the 
* Unicode characters. Astral planes are supported ie. the ints in the
* output can be > 0xFFFF. Occurrances of the BOM are ignored. Surrogates
* are not allowed.
* Returns false if the input string isn't a valid UTF-8 octet sequence
* and raises a PHP error at level E_USER_WARNING
* Note: this function has been modified slightly in this library to
* trigger errors on encountering bad bytes
* @author <[email protected]>
* @param string UTF-8 encoded string
* @return mixed array of unicode code points or FALSE if UTF-8 invalid
* @see utf8_from_unicode
* @see http://hsivonen.iki.fi/php-utf8/
* @package utf8
* @subpackage unicode
*/
function utf8_to_unicode($str) {
$mState = 0;
$mUcs4  = 0;
$mBytes = 1;

$out = array();

$len = strlen($str);

for($i = 0; $i < $len; $i++) {

	$in = ord($str{$i});

	if ( $mState == 0) {

		if (0 == (0x80 & ($in))) {
			$out[] = $in;
			$mBytes = 1;

		} else if (0xC0 == (0xE0 & ($in))) {
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 0x1F) << 6;
			$mState = 1;
			$mBytes = 2;

		} else if (0xE0 == (0xF0 & ($in))) {
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 0x0F) << 12;
			$mState = 2;
			$mBytes = 3;

		} else if (0xF0 == (0xF8 & ($in))) {
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 0x07) << 18;
			$mState = 3;
			$mBytes = 4;

		} else if (0xF8 == (0xFC & ($in))) {
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 0x03) << 24;
			$mState = 4;
			$mBytes = 5;

		} else if (0xFC == (0xFE & ($in))) {
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 1) << 30;
			$mState = 5;
			$mBytes = 6;

		} else {
			trigger_error(
					'utf8_to_unicode: Illegal sequence identifier '.
						'in UTF-8 at byte '.$i,
					E_USER_WARNING
				);
			return FALSE;

		}

	} else {

		if (0x80 == (0xC0 & ($in))) {

			$shift = ($mState - 1) * 6;
			$tmp = $in;
			$tmp = ($tmp & 0x0000003F) << $shift;
			$mUcs4 |= $tmp;

			if (0 == --$mState) {

				if (((2 == $mBytes) && ($mUcs4 < 0x0080)) ||
					((3 == $mBytes) && ($mUcs4 < 0x0800)) ||
					((4 == $mBytes) && ($mUcs4 < 0x10000)) ||
					(4 < $mBytes) ||
					(($mUcs4 & 0xFFFFF800) == 0xD800) ||
					($mUcs4 > 0x10FFFF)) {

					trigger_error(
							'utf8_to_unicode: Illegal sequence or codepoint '.
								'in UTF-8 at byte '.$i,
							E_USER_WARNING
						);

					return FALSE;

				}

				if (0xFEFF != $mUcs4) {
					$out[] = $mUcs4;
				}

				$mState = 0;
				$mUcs4  = 0;
				$mBytes = 1;
			}

		} else {
			trigger_error(
					'utf8_to_unicode: Incomplete multi-octet '.
					'   sequence in UTF-8 at byte '.$i,
					E_USER_WARNING
				);

			return FALSE;
		}
	}
}
return $out;
}

Jeg tviler på at de færreste kunne på sparket forklart hva som foregår her. Man skjønner at det er konvertering fra UTF-8 til Unicode (UCS-4-lignende greier), men uten å ha jobbet med Unicode på lavnivå før har man ingen ide om at alt over 0x10FFFF er utenfor Unicode-tegnsettet pr. dags dato, eller at hvis ($mUcs4 & 0xFFFFF800) == 0xD800 er true betyr det at tegnet er surrogat og er ulovlig i UTF-8. At ((2 == $mBytes) && ($mUcs4 < 0x0080)), ((3 == $mBytes) && ($mUcs4 < 0x0800)) og ((4 == $mBytes) && ($mUcs4 < 0x10000)) sjekker om tegnet er non-shortest form er det nok også ganske umulig å få med seg uten forkunnskaper og god hukommelse.

 

Til sammenligning så vi koden over med tilhørende kommentarer:

/**
* Takes an UTF-8 string and returns an array of ints representing the 
* Unicode characters. Astral planes are supported ie. the ints in the
* output can be > 0xFFFF. Occurrances of the BOM are ignored. Surrogates
* are not allowed.
* Returns false if the input string isn't a valid UTF-8 octet sequence
* and raises a PHP error at level E_USER_WARNING
* Note: this function has been modified slightly in this library to
* trigger errors on encountering bad bytes
* @author <[email protected]>
* @param string UTF-8 encoded string
* @return mixed array of unicode code points or FALSE if UTF-8 invalid
* @see utf8_from_unicode
* @see http://hsivonen.iki.fi/php-utf8/
* @package utf8
* @subpackage unicode
*/
function utf8_to_unicode($str) {
$mState = 0;	 // cached expected number of octets after the current octet
				 // until the beginning of the next UTF8 character sequence
$mUcs4  = 0;	 // cached Unicode character
$mBytes = 1;	 // cached expected number of octets in the current sequence

$out = array();

$len = strlen($str);

for($i = 0; $i < $len; $i++) {

	$in = ord($str{$i});

	if ( $mState == 0) {

		// When mState is zero we expect either a US-ASCII character or a
		// multi-octet sequence.
		if (0 == (0x80 & ($in))) {
			// US-ASCII, pass straight through.
			$out[] = $in;
			$mBytes = 1;

		} else if (0xC0 == (0xE0 & ($in))) {
			// First octet of 2 octet sequence
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 0x1F) << 6;
			$mState = 1;
			$mBytes = 2;

		} else if (0xE0 == (0xF0 & ($in))) {
			// First octet of 3 octet sequence
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 0x0F) << 12;
			$mState = 2;
			$mBytes = 3;

		} else if (0xF0 == (0xF8 & ($in))) {
			// First octet of 4 octet sequence
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 0x07) << 18;
			$mState = 3;
			$mBytes = 4;

		} else if (0xF8 == (0xFC & ($in))) {
			/* First octet of 5 octet sequence.
			*
			* This is illegal because the encoded codepoint must be either
			* (a) not the shortest form or
			* (b) outside the Unicode range of 0-0x10FFFF.
			* Rather than trying to resynchronize, we will carry on until the end
			* of the sequence and let the later error handling code catch it.
			*/
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 0x03) << 24;
			$mState = 4;
			$mBytes = 5;

		} else if (0xFC == (0xFE & ($in))) {
			// First octet of 6 octet sequence, see comments for 5 octet sequence.
			$mUcs4 = ($in);
			$mUcs4 = ($mUcs4 & 1) << 30;
			$mState = 5;
			$mBytes = 6;

		} else {
			/* Current octet is neither in the US-ASCII range nor a legal first
			 * octet of a multi-octet sequence.
			 */
			trigger_error(
					'utf8_to_unicode: Illegal sequence identifier '.
						'in UTF-8 at byte '.$i,
					E_USER_WARNING
				);
			return FALSE;

		}

	} else {

		// When mState is non-zero, we expect a continuation of the multi-octet
		// sequence
		if (0x80 == (0xC0 & ($in))) {

			// Legal continuation.
			$shift = ($mState - 1) * 6;
			$tmp = $in;
			$tmp = ($tmp & 0x0000003F) << $shift;
			$mUcs4 |= $tmp;

			/**
			* End of the multi-octet sequence. mUcs4 now contains the final
			* Unicode codepoint to be output
			*/
			if (0 == --$mState) {

				/*
				* Check for illegal sequences and codepoints.
				*/
				// From Unicode 3.1, non-shortest form is illegal
				if (((2 == $mBytes) && ($mUcs4 < 0x0080)) ||
					((3 == $mBytes) && ($mUcs4 < 0x0800)) ||
					((4 == $mBytes) && ($mUcs4 < 0x10000)) ||
					(4 < $mBytes) ||
					// From Unicode 3.2, surrogate characters are illegal
					(($mUcs4 & 0xFFFFF800) == 0xD800) ||
					// Codepoints outside the Unicode range are illegal
					($mUcs4 > 0x10FFFF)) {

					trigger_error(
							'utf8_to_unicode: Illegal sequence or codepoint '.
								'in UTF-8 at byte '.$i,
							E_USER_WARNING
						);

					return FALSE;

				}

				if (0xFEFF != $mUcs4) {
					// BOM is legal but we don't want to output it
					$out[] = $mUcs4;
				}

				//initialize UTF8 cache
				$mState = 0;
				$mUcs4  = 0;
				$mBytes = 1;
			}

		} else {
			/**
			*((0xC0 & (*in) != 0x80) && (mState != 0))
			* Incomplete multi-octet sequence.
			*/
			trigger_error(
					'utf8_to_unicode: Incomplete multi-octet '.
					'   sequence in UTF-8 at byte '.$i,
					E_USER_WARNING
				);

			return FALSE;
		}
	}
}
return $out;
}

 

Jeg veit hvilken versjon jeg foretrekker å lese, og jeg skjønner i stor grad den første versjonen også ...

Endret 27. mai 2009 av Ernie

[[kami]]

helt enig med Ernie & Jonas her.

 

På større programmeringsprosjekter skal jo koden ofte ikke maintaines av deg, så kommentarer er ekstremt viktig for fyren som skal se på koden din og skjønne hvordan du har tenkt. Heck, om du skal se på din egen kode etter et års tid er det kjekt med kommentarer for å skjønne hvordan hjernen funka der og da

 

snakker av erfaring etter å ha jobbet 5 år på større prosjekter med ca 30 programmører. (c++ kode, men dette gjelder også i php)

Kommentarer, lesbar kode og kodestandarer er utrolig viktig.

[JcV]

Ernie: Vel du kom vel egentlig ikke med noe godt poeng her. Jeg sa at det man kanskje bør kommentere er struktur og avanserte algoritmer, slik som denne du gir som et eksempel her.

 

Men jeg finner ikke denne koden til å være et godt eksempel, den er både lang (bør deles opp i flere ledd som kan testes individuelt.)og variablene dine er lite beskrivende. $mUcs4 ville ikke ha sagt meg eller noen andre noe som helst. Derfor MÅ man kommentere dette for å forstå hva som hender.

 

Poenget mitt er at man bør heller bruke mer tid på å skrive mindre og ryddig kode framfor eksemplet ditt her.

[Ernie]

Ernie: Vel du kom vel egentlig ikke med noe godt poeng her. Jeg sa at det man kanskje bør kommentere er struktur og avanserte algoritmer, slik som denne du gir som et eksempel her.

 

Men jeg finner ikke denne koden til å være et godt eksempel, den er både lang (bør deles opp i flere ledd som kan testes individuelt.)og variablene dine er lite beskrivende. $mUcs4 ville ikke ha sagt meg eller noen andre noe som helst. Derfor MÅ man kommentere dette for å forstå hva som hender.

 

Poenget mitt er at man bør heller bruke mer tid på å skrive mindre og ryddig kode framfor eksemplet ditt her.

Det der er ikke mye avansert algoritme, men heller bare trivielle bit-operasjoner. Det som ikke er trivielt er hvorfor man gjør disse operasjonene, og de kommer de ikke unna. Du kan dele koden opp så mye du vil, men de må uannsett gjennomføres og det er vanskelig å gjøre det noe anderledes. Det er f.eks. vanskelig å komme unna denne if-en

 

/*
* Check for illegal sequences and codepoints.
*/
// From Unicode 3.1, non-shortest form is illegal
if (((2 == $mBytes) && ($mUcs4 < 0x0080)) ||
((3 == $mBytes) && ($mUcs4 < 0x0800)) ||
((4 == $mBytes) && ($mUcs4 < 0x10000)) ||
(4 < $mBytes) ||
// From Unicode 3.2, surrogate characters are illegal
(($mUcs4 & 0xFFFFF800) == 0xD800) ||
// Codepoints outside the Unicode range are illegal
($mUcs4 > 0x10FFFF)) {

Består tegnet av 2 bytes skal verdien være 0x80 eller høyere, ellers er det ugyldig. Er det 3 bytes skal den være større enn 0x800, ellers er den ugyldig, osv. Dette er helt trivielle operasjoner i seg selv, men selv om man gir de mer beskrivende navn så sier det fortsatt ingenting om hvorfor den må være større eller lik 0x80, 0x800 osv. Det er det som er hovedessensen. Det er ikke alltid man kan skrive ting på en svært forståelig måte. Siden du på tross av dette mener av kommentarer er overflødig fordi man heller bør skrive det mindre og ryddigere. Hvordan burde denne koden vært skrevet? At man kan splitte opp koden er en ting, men bitoperasjonene kommer man ikke unna. De må gjennomføres på en eller annen måte.

 

Forøvrig har hverken jeg eller noen jeg kjenner har skrevet den koden