Dando nome aos códigos

Dando Nome aos Códigos
@nelson_senna

“Existem duas coisas difíceis em
Ciência da Computação:
invalidação de cache e nomear
coisas.”
— Phil Karlton

“palavra ou locução com que se
designa uma classe de coisas,
pessoas, animais, um lugar, um
acidente geográﬁco, um astro
etc.;”
Nome

O processo de descoberta
Sem nome Sem sentido Honesto
Honesto e
Completo
Faz o que o
nome diz
Intenção
Abstração de
domínio
↪ ↪ ↪ ↪ ↪ ↪

Honesto e
Completo
Faz o que o
nome diz
Intenção
Abstração de
domínio
↪ ↪ ↪ ↪ ↪ ↪
@arlobelshee

Honesto e
Completo
Faz o que o
nome diz
Intenção
Abstração de
domínio
↪ ↪ ↪ ↪ ↪ ↪
@arlobelshee
Vamos até aqui!

<?php
/**
* Returns an array of the contents of the current directory.
* The returned array holds two arrays: One of directories and one of files.
*
* @param string|bool $sort Whether you want the results sorted, set this and the sort property
* to false to get unsorted results.
* @param array|bool $exceptions Either an array or boolean true will not grab dot files
* @param bool $fullPath True returns the full path
* @return array Contents of current directory as an array, an empty array on failure
*/
public function read($sort = self::SORT_NAME, $exceptions = false, $fullPath = false)
{
$dirs = $files = [];
if (!$this->pwd()) {
return [$dirs, $files];
}
if (is_array($exceptions)) {
$exceptions = array_flip($exceptions);
}
$skipHidden = isset($exceptions['.']) || $exceptions === true;
try {
$iterator = new DirectoryIterator($this->path);
} catch (Exception $e) {
}
if (!is_bool($sort) && isset($this->_fsorts[$sort])) {
$methodName = $this->_fsorts[$sort];
} else {
$methodName = $this->_fsorts[self::SORT_NAME];
}
foreach ($iterator as $item) {
if ($item->isDot()) {
continue;
}
$name = $item->getFilename();
if ($skipHidden && $name[0] === '.' || isset($exceptions[$name])) {
continue;
}
if ($fullPath) {
$name = $item->getPathname();
}
if ($item->isDir()) {
$dirs[$item->{$methodName}()][] = $name;
} else {
$files[$item->{$methodName}()][] = $name;
}
}
if ($sort || $this->sort) {
ksort($dirs);
ksort($files);
}
if ($dirs) {
$dirs = array_merge(...array_values($dirs));
}
if ($files) {
$files = array_merge(...array_values($files));
}
}
Nosso código
↳

<?php
/**
*
*/
{
}
}
try {
}
} else {
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
ksort($dirs);
ksort($files);
}
if ($dirs) {
}
if ($files) {
}
}
/**
*
*/
Assinatura
↳

<?php
/**
*
*/
{
}
}
try {
}
} else {
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
ksort($dirs);
ksort($files);
}
if ($dirs) {
}
if ($files) {
}
}
/**
*
*/
Parâmetros booleanos…

<?php
/**
*
*/
{
}
}
try {
}
} else {
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
ksort($dirs);
ksort($files);
}
if ($dirs) {
}
if ($files) {
}
}
/**
*
*/

<?php
/**
*
*/
{
}
}
try {
}
} else {
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
ksort($dirs);
ksort($files);
}
if ($dirs) {
}
if ($files) {
}
}
Um loop com if, eh?

<?php
/**
*
*/
{
}
}
try {
}
} else {
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
ksort($dirs);
ksort($files);
}
if ($dirs) {
}
if ($files) {
}
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
Sem nome!

private function getLists($iterator, $methodName, $exceptions, $skipHidden, $fullPath)
{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
}
Nome sem sentido
↳

{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
continue;
}
continue;
}
Hmmm, um ﬁltro!

{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
} else {
}
Cria uma lista de pastas e, 
outra lista de arquivos

private function iterateOverItemsToCreateSortableMapOfFilesAndDirs(
$iterator, $methodName, $exceptions, $skipHidden, $fullPath)
{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
}
Honesto!

private function iterateOverItemsToCreateSortableMapOfFilesAndDirs(
{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
}
continue;
}
continue;
}
Hmmm, um ﬁltro!

private function iterateOverItemsToCreateSortableMapOfFilesAndDirsSkippingExceptions(
{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
}
Honesto e completo!

{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
}
Olha o ﬁltro aí!

{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
}

{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
}
Relação!

Características de bons nomes de métodos
•Use verbos;
•Sem abreviações;
•Conciso (mas, não muito!);
•Use perguntas quando o método retornar um boolean (isEmpty(), canDo());
•Não use “And” e “Or” nos seus nomes;
•Não deixe o nome redundante com o argumento 
($list->addItem($item));
•Não deixe o nome redundante com quem chama 
($list->addToList($item));

{
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
}
Guard Clauses
continue;
}
continue;
}

private function isFileRelevant($item, $skipHidden, $ignoredFiles)
{
return false;
}
$isHiddenFile = $name[0] === '.';
$ignored = isset($ignoredFiles[$name]);
if ($skipHidden && $isHiddenFile || $ignored) {
return false;
}
return true;
}

Bom nome?
•Use verbos √
•Sem abreviações √
•Conciso (mas, não muito!) √
•Use perguntas quando o método retornar um boolean (isEmpty(), canDo()) √
•Não use “And” e “Or” nos seus nomes √
•Não deixe o nome redundante com o argumento √ 
($list->addItem($item));
•Não deixe o nome redundante com quem chama √ 
($list->addToList($item));

{
if ($this->isFileRelevant($item, $skipHidden, $exceptions)) {
$name = $fullPath ? $item->getPathname() : $item->getFilename();
} else {
}
}
}
}

{
if ($this->isFileRelevant($item, $skipHidden, $exceptions)) {
} else {
}
}
}
}
Extrair comportamento pra 
sua própria classe

Características de bons nomes de classes
•Use substantivos e adjetivos*;
•Não use muitos adjetivos (AbstractFactoryPatternBase);
•Não use “Manager”, “Helper” e “Data” nos seus nomes;
•Não use Suﬁxos do seu namespace (Service, Factory,
Iterator)
•Evite usar “er”, “or”, “tion”, “sion” (ObjectFinder,
DataProcessor, Conversion, DataManipulation)

–Chris Oldwood
“So, a "DateTimeProvider", that's basically just a clock, right?”

Características de bons nomes de classes
Service is the new Enzo

{
return false;
}
return false;
}
return true;
}
Filtro para arquivos 
ocultos

{
return false;
}
return false;
}
return true;
}
Filtro para arquivos 
ignorados

namespace Filter;
class Visible extends FilterIterator
{
public function accept()
{
$item = $this->getInnerIterator()->current();
$isDotEntry = $name[0] === '.';
return !$isDotEntry;
}
}

namespace Filter;
class IgnoreList extends FilterIterator
{
private $list = [];
public function __construct(Iterator $iterator, $list)
{
parent::__construct($iterator);
$this->list = $list;
}
public function accept()
{
return false;
}
$item = $this->getInnerIterator()->current();
$relevant = !isset($this->list[$item->getFilename()]);
return $relevant;
}
}

private function applyContentFilters(Iterator $iterator, $ignoreList, $skipHidden)
{
if ($skipHidden) {
$iterator = new FilterVisible($iterator);
}
return new FilterIgnoreList($iterator, $ignoreList);
}

private function createSortableMapOfFilesAndDirs($iterator, $methodName, $fullPath)
{
} else {
}
}
}
Iterator já ﬁltrado!

private function createSortableMapOfFilesAndDirs($iterator, $methodName, $fullPath)
{
} else {
}
}
}
Remover a ordenação 
daqui!

No método
principal, caçar o
que ainda não tem
nome!

<?php
/**
*
*/
{
}
}
try {
}
} else {
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
ksort($dirs);
ksort($files);
}
if ($dirs) {
}
if ($files) {
}
}
}
if ($dirs) {
}
if ($files) {
}
Implementação 
“rústica” de Set

<?php
/**
*
*/
{
}
}
try {
}
} else {
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
ksort($dirs);
ksort($files);
}
if ($dirs) {
}
if ($files) {
}
}
/**
*
*/
Nome
“nonsense”
↳

<?php
/**
*
*/
{
}
}
try {
}
} else {
}
continue;
}
continue;
}
if ($fullPath) {
}
} else {
}
}
ksort($dirs);
ksort($files);
}
if ($dirs) {
}
if ($files) {
}
}
/**
*
*/
Nome
“nonsense”
↳
Conﬁguração em runtime? 
Builder Pattern!

DirectoryContents::of($path)
->excluding($irrelevantFiles)
->orderedByName() // ou orderedByLastModification
->includeHiddenContent()
->list(); // ou listWithFullPath()

Informação essencial 
pra construir a classe

Exceções

Ordenação

->excludeHiddenContent()
Incluir ou não arquivos ocultos

O resultado após as 
conﬁgurações serem 
aplicadas

Concluindo…
1. Procure por lugares com mais de um nível de indentação
2. Extraia e dê nome para o que ﬁzer sentido
3. Descreva o que o método realmente faz, sem vergonha, seja honesto!
4. Vá diminuindo o nome do método extraindo suas responsabilidades
5. Excesso de métodos privados para um dado contexto: Uma nova classe!
6. Procure na documentação ou fale com um amiguinho para descrever 
o problema de domínio resolvido
7. Seja feliz!

Referências
•http://arlobelshee.com/good-naming-is-a-process-not-a-single-
step/
•http://journal.stuffwithstuff.com/2009/06/05/naming-things-
in-code/
•https://martinfowler.com/bliki/TwoHardThings.html
•https://www.infoq.com/articles/implementations-patterns-br

Dando nome aos códigos

Recommended

Recommended

More Related Content

What's hot

What's hot (18)

Similar to Dando nome aos códigos

Similar to Dando nome aos códigos (20)

More from Nelson Senna do Amaral

More from Nelson Senna do Amaral (10)

Recently uploaded

Recently uploaded (20)

Dando nome aos códigos