Conceitos
Números de semana, e por que razão os do calendário são os errados
Todas as instituições numeram as suas semanas letivas, quase nenhuma as numera como o calendário o faz, e é nessa diferença que vive uma quantidade surpreendente de confusão.
Dois números diferentes com o mesmo nome
Pergunte ao calendário em que semana estamos e obterá o número de semana ISO: a semana 1 é a que contém a primeira quinta-feira de janeiro e, no início de um ano académico do hemisfério norte, estamos por volta da semana 36 a 40.
Faça a mesma pergunta a um gabinete de horários e obterá um número completamente diferente. A semana 1 é a primeira semana letiva do ano, em qualquer ponto do calendário em que calhe, e tudo é contado a partir daí. É o número impresso no horário, o número no formulário de reserva de salas e o número que dois colegas usam quando combinam encontrar-se na semana 9.
Os dois nunca coincidem, a menos que o ano letivo de uma instituição comece por acaso na primeira semana de janeiro, ou seja: nunca. E como ambos se chamam o número da semana, o software que produz silenciosamente o errado produz algo que parece inteiramente plausível.
Como se manifesta quando corre mal
Não parece um erro. Parece uma página com um número no topo, e o número está errado numa medida diferente em cada instituição — porque cada uma começa o seu ano numa data diferente.
É isso que o torna dispendioso. Uma falha grave é comunicada numa hora. Um título que diz Semana 36 quando todos no edifício lhe chamam Semana 2 é comunicado semanas depois, por alguém que presumiu ter percebido mal o sistema e não que o sistema o tinha percebido mal — e entretanto as pessoas têm-se dirigido a salas com base nisso.
A regra que o evita é curta: um número de semana é lido, nunca calculado. A instituição decide onde está a semana 1; o trabalho do software é indicar o que a instituição decidiu, e não derivar um número próprio a partir de uma data.
A semana 1 nem sempre é a primeira semana que existe
As instituições precisam rotineiramente de datas anteriores ao seu ano letivo: uma quinzena de acolhimento, um período de exames de recurso, uma escola de verão que pertence ao ano que termina. Em vez de renumerar tudo — o que alteraria silenciosamente o significado de cada horário, de cada reserva e de cada mensagem alguma vez enviada sobre a semana 9 — a solução sensata é alargar o calendário para trás, para o zero e para números negativos.
Parece estranho à primeira vez e é exatamente correto à segunda: a semana 1 continua a significar o que sempre significou, e a quinzena anterior é a semana −1 e a semana −2. Temos instituições cuja tabela de semanas se estende muito para o negativo e muito para além do fim do ano letivo, e tudo o que fica no meio corresponde a uma data real.
Qualquer sistema que leia um horário programaticamente deve esperar isso. Um número de semana é um inteiro com sinal, e não um contador que começa em um.
E algumas instituições não usam números de todo
Oxford e Cambridge dão nomes às semanas por período, em vez de as contarem ao longo do ano: uma data está na Michaelmas fourth week, e um número não significaria nada para ninguém na sala. Outras instituições designam uma quinzena como Revisão, Acolhimento ou Período de avaliação e esperam que o horário o diga.
Assim, uma semana letiva tem duas coisas e não uma: o número pelo qual o software a endereça e o nome que a própria instituição lhe dá, que é o que o leitor realmente quer no topo da página. Quando existe um nome, deve ser impresso em vez do número e impresso por extenso — abreviar a convenção de períodos de alguém para poupar oito píxeis é o tipo de prestabilidade que ninguém pediu.
Quando não existe nome, e para a maioria das instituições não existe, o número é o nome e isso é perfeitamente aceitável.
Quatro aspetos a verificar em qualquer sistema de horários
Nenhum é exótico. Todos estão silenciosamente errados nalgum lado.
| Pergunta | Como é uma boa resposta |
|---|---|
| Onde começa a semana 1? | Uma data definida pela sua instituição, guardada uma vez e usada em todo o lado. Não derivada do calendário nem configurável por ecrã. |
| O calendário pode recuar para antes da semana 1? | Sim, para o zero e números negativos, sem renumerar nada do que já existe. |
| Uma semana pode ter um nome? | Sim, e o nome é impresso em vez do número, por extenso. |
| De onde obtém uma aplicação para estudantes o número? | Do horário, na mesma resposta que as aulas. Um cliente que calcule o seu próprio estará errado, e errado de forma diferente em cada instituição. |
Por que razão isto é também uma questão de integração
Um portal, uma aplicação ou um ecrã informativo que mostre um título de semana tem de o obter de algum lado, e a única fonte que pode estar certa é o próprio horário. No Wise Timetable, a resposta do calendário inclui os números e os nomes das semanas do intervalo que abrange, pelo que um cliente nunca tem motivo para os calcular — e GET /v2/weeks responde sozinho à mesma pergunta, para um ecrã que precisa de rotular um período inteiro de uma só vez.
O manual da API REST documenta ambos, incluindo o caso negativo, e é publicado na íntegra e sem restrições para que um programador possa verificar a forma da resposta antes de alguém assinar o que quer que seja.
Quer ver isto a funcionar?
Marque uma apresentação online de 45 minutos e percorreremos a solução com base no problema de planeamento de horários da sua própria instituição.