Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Inconsistent method naming in LicenseCompareHelper

Abierto
  • ¿Algo no está bien?
#392 4 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Refactorización
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
java
Área
backend

Línea de trabajo

Comienza con la clase org.spdx.utility.compare.LicenseCompareHelper y su Javadoc; después, haz un inventario de las firmas de los métodos existentes de matching y diff frente a la matriz propuesta. Revisa cómo se utilizan los métodos actuales antes de definir nombres coherentes, delegaciones de compatibilidad y deprecaciones. Se considera terminado cuando el esquema de nombres esté implementado sin eliminar los métodos antiguos antes de una versión major.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

matching

Problem Statement

I've found that the names of the various different permutations of the matching methods in the org.spdx.utility.compare.LicenseCompareHelper class are pretty confusing, and wonder if a more consistent naming scheme would be valuable?

This is partly fueled by:

  • There is no overall pattern to how the various methods are named, making "at a glance inference of method variations" difficult.
  • There are some missing permutations (e.g. see #391).
  • There are inconsistencies in how exceptions are referred to (some methods use "LicenseException", while others use "Exception").
  • There's conflation of "pure" matching methods (i.e. methods that answer the question "did this text contains one or more licenses / exceptions, and (optionally) if so, which ones?") with the methods that calculate diffs (i.e. methods that answer the question "what, if any, differences exist between this text and a given license / exception?").

It seems to me that the methods in this class fall into a sparse matrix defined by these criteria:

  1. Whether the method operates on licenses, or exceptions
  2. Whether the method performs exact matching of the text, or "finding" within the text
  3. Whether the method considers only one listed license / exception, or multiple listed licenses / exceptions (and in the latter case, whether that's all listed licenses / exceptions, or a subset provided by the caller)
  4. Whether the method returns the first match, or all matches
  5. Whether the method is concerned with "pure" matching, or calculating differences

Coming up with a systematic naming scheme informed by these criteria has substantial value in helping to communicate how the LicenseCompareHelper class can be used for different matching / diffing scenarios.

A Proposed Naming Scheme

Methods that perform exact matching of the entire text:
Method Signature Notes
boolean isLicense(ListedLicense lic, String text)
boolean isException(ListedLicenseException exc, String text)
String isOneOfTheseLicenses(List<ListedLicense> lics, String text) Returns the id of the first listed license in lics that matched, or null if no match was found
String isOneOfTheseExceptions(List<ListedLicenseException> excs, String text) Returns the id of the first listed exception in excs that matched, or null if no match was found
String isAnyLicense(String text) Returns the id of the first listed license that matched, or null if no match was found
String isAnyException(String text) Returns the id of the first listed exception that matched, or null if no match was found
List<String> listAllLicensesMatched(List<ListedLicense> lics, String text) Returns the ids of all of the listed licenses in lics that matched, or null if no match was found. Might not be necessary, as this is a corner case for overlapping matching templates (e.g. GPL).
List<String> listAllExceptionsMatched(List<ListedLicenseException> excs, String text) Returns the ids of all of the listed exceptions in excs that matched, or null if no match was found. Might not be necessary, as this is a corner case for overlapping matching templates (e.g. GPL).
List<String> listAllLicensesMatched(String text) Returns the ids of all of the listed licenses that matched, or null if no match was found. Might not be necessary, as this is a corner case for overlapping matching templates (e.g. GPL).
List<String> listAllExceptionsMatched(String text) Returns the ids of all of the listed exceptions that matched, or null if no match was found. Might not be necessary, as this is a corner case for overlapping matching templates (e.g. GPL).
Methods that perform finds within the text, but only return the first match:
Method Signature Notes
boolean containsLicense(ListedLicense lic, String text)
boolean containsException(ListedLicenseException exc, String text)
String containsOneOfTheseLicenses(List<ListedLicense> lics, String text) Returns the id of the first listed license in lics that matched, or null if no match was found
String containsOneOfTheseExceptions(List<ListedLicenseException> excs, String text) Returns the id of the first listed exception in excs that matched, or null if no match was found
String containsAnyLicense(String text) Returns the id of the first listed license that matched, or null if no match was found
String containsAnyException(String text) Returns the id of the first listed exception that matched, or null if no match was found
Methods that perform finds within the text, and return all matches:
Method Signature Notes
List<String> listAllLicensesFound(List<ListedLicense> lics, String text) Returns the ids of all of the listed licenses in lics that matched, or null if no match was found
List<String> listAllExceptionsFound(List<ListedLicenseException> excs, String text) Returns the ids of all of the listed exceptions in excs that matched, or null if no match was found
List<String> listAllLicensesFound(String text) Returns the ids of all of the listed licenses that matched, or null if no match was found
List<String> listAllExceptionsFound(String text) Returns the ids of all of the listed exceptions that matched, or null if no match was found
Methods that calculate diffs:
Method Signature Notes
CompareTemplateOutputHandler.DifferenceDescription diffLicense(ListedLicense lic, String text)
CompareTemplateOutputHandler.DifferenceDescription diffException(ListedLicenseException exc, String text)

Notes:

  • Many of these methods will share a common implementation - in fact in many cases they can be implemented as simple delegation calls to other methods (sometimes in a loop).
  • Obviously the old method names can't be removed until the next major release of the library, but they could be re-implemented to simply delegate to the new methods, and marked as deprecated before then.
  • I don't believe any of the method signatures listed above conflict with existing method signatures, but haven't done an exhaustive check.
Lenguaje dominante
Java
Estrellas
71
Forks
44
Merge medio
16 h 17 min
PR fusionados (30 d)
9

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de spdx/Spdx-Java-Library

Todos los issues de spdx/Spdx-Java-Library

Issues similares

Más issues de Java

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.